This document explains how to view Batch jobs and tasks.
Before you begin
- If you haven't used Batch before, review Get started with Batch and enable Batch by completing the prerequisites for projects and users.
-
To get the permissions that you need to view jobs and tasks, ask your administrator to grant you the Batch Job Viewer (
roles/batch.jobsViewer
) or Batch Job Editor (roles/batch.jobsEditor
) IAM role on the project. For more information about granting roles, see Manage access to projects, folders, and organizations.You might also be able to get the required permissions through custom roles or other predefined roles.
View your jobs
To view your jobs, select one of the following methods:
To see all the jobs in your project, view a list of your jobs.
To see all the configuration details of a specific job, view the details of a job.
View a list of your jobs
You can view a list of jobs in the current project using the Google Cloud console, gcloud CLI, Batch API, Go, Java, Node.js, Python, or C++.
Console
To view a list of jobs in the current project using the Google Cloud console, go to the Job list page.
The list of jobs might be multiple pages. If you need to continue to the next page, click
Next at the bottom of the screen.Optional: If you want to filter the list of jobs, click
Filter. Then, type or select a property and a value.For example, to filter the list to only include jobs in a specific state, enter the following:
Status:JOB_STATE
Replace
JOB_STATE
with a job state—for example,FAILED
.
gcloud
View all jobs
To view a list of jobs in the current project using the
gcloud CLI, use the
gcloud batch jobs list
command.
gcloud batch jobs list
View a filtered list of jobs
Optionally, you can add one or more flags to view a filtered list of jobs:
To only view jobs in a specific location, include the
--location
flag.To only view jobs based on a filter expression, specify the
--filter
flag.
For example, use the following command:
gcloud batch jobs list \
--location=LOCATION \
--filter="FILTER_EXPRESSION"
Replace the following:
LOCATION
: the location where one or more jobs exist.FILTER_EXPRESSION
: a filter expression that defines the jobs that you want to list. The filter expression must define one or more property-value pairs that are separated by zero or more boolean operators (AND
,OR
andNOT
).For example, see the following filter expressions:
Filter based on job state: To only view jobs that are in a specific state, use the following filter expression:
status.state="JOB_STATE"
Replace
JOB_STATE
with a job state—for example,FAILED
.Filter based on labels: Suppose that your project has defined the following custom labels:
To indicate jobs and their resources that are created by your research team when you view Cloud Billing reports, some of your jobs and their resources have a
team
label that is set toresearch
.To indicate time-sensitive workloads, some jobs have a
deadline
label, which is set to various values.To indicate runnables that your development team has successfully tested, some runnables have a
tested
label that is set totrue
.
Then, you might specify the following filter expression:
(allocationPolicy.labels.team=research) AND ((labels.deadline:*) OR (runnables.labels.tested=true))
This filter expression only lists jobs that meet all of the following criteria:
Jobs that are from the research team, which have a
team
label on the job's allocation policy that is set toresearch
.Jobs that meet at least one of the following criteria:
Jobs that are time-sensitive, which have a
deadline
label on the job that is set to any value.Jobs that have at least one runnable that has been successfully tested, which are jobs that have at least one runnable with a
tested
label that is set totrue
.
API
View all jobs
To view a list of jobs in the current project for a specific location using
the Batch API, make a GET
request to the
jobs.list
method.
GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs
Replace the following:
PROJECT_ID
: the project ID of your current project.LOCATION
: the location where the jobs exist.
View a filtered list of jobs
Optionally, you can specify the filter
query parameter to view a filtered
list of jobs based on a filter expression.
For example, make the following GET
request:
GET https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs?filter=FILTER_EXPRESSION
Replace FILTER_EXPRESSION
with a
filter expression
that uses URL-encoding.
The filter expression must define one or more property-value pairs that are
separated by zero or more
boolean operators (AND
, OR
and NOT
).
For example, see the following filter expressions:
Filter based on job state: To only view jobs that are in a specific state, use the following filter expression:
status.state="JOB_STATE"
Replace
JOB_STATE
with a job state—for example,FAILED
.Filter based on labels: Suppose that your project has defined the following custom labels:
To indicate jobs and their resources that are created by your research team when you view Cloud Billing reports, some of your jobs and their resources have a
team
label that is set toresearch
.To indicate time-sensitive workloads, some jobs have a
deadline
label, which is set to various values.To indicate runnables that your development team has successfully tested, some runnables have a
tested
label that is set totrue
.
Then, you might specify the following filter expression:
(allocationPolicy.labels.team%3Dresearch)%20AND%20((labels.deadline%3A*)%20OR%20(runnables.labels.tested%3Dtrue))
This filter expression only lists jobs that meet all of the following criteria:
Jobs that are from the research team, which have a
team
label on the job's allocation policy that is set toresearch
.Jobs that meet at least one of the following criteria:
Jobs that are time-sensitive, which have a
deadline
label on the job that is set to any value.Jobs that have at least one runnable that has been successfully tested, which are jobs that have at least one runnable with a
tested
label that is set totrue
.
Go
Go
For more information, see the Batch Go API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
For more information, see the Batch Java API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Node.js
For more information, see the Batch Node.js API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
For more information, see the Batch Python API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C++
C++
For more information, see the Batch C++ API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
View the details of a job
You can view the details a job in the current project using the Google Cloud console, gcloud CLI, Batch API, Go, Java, Node.js, Python, or C++.
Console
To view the details of a job in the current project using the Google Cloud console, follow these steps:
In the Google Cloud console, go to the Job list page.
In the Job name column, click the name of a job.
The Job details page opens.
The Details tab is open by default. For more information, click other tabs.
gcloud
To view the details of a job in the current project using the
gcloud CLI, use the
gcloud batch jobs describe
command
with the --location
flag.
gcloud batch jobs describe JOB_NAME \
--location=LOCATION
Replace the following:
JOB_NAME
: the name of an existing job.LOCATION
: the location where the job exists.
API
To view the details of a job in the current project using the
Batch API, make a GET
request to the
jobs.get
method.
GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME
Replace the following:
PROJECT_ID
: the project ID of the current project.LOCATION
: the location where the job exists.JOB_NAME
: the name of an existing job.
Go
Go
For more information, see the Batch Go API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
For more information, see the Batch Java API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Node.js
For more information, see the Batch Node.js API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
For more information, see the Batch Python API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C++
C++
For more information, see the Batch C++ API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
View tasks
To view the tasks for one of your jobs, select one of the following methods:
To see all the tasks in a job or a job's task group, view a list of a job's tasks.
To see all the configuration details of a specific task, view the details of a task.
View a list of a job's tasks
You can view a list of the tasks in a job or a job's task group using the Google Cloud console, gcloud CLI, Batch API, Go, Java, Node.js, Python, or C++.
If you want to filter a list of tasks in a job or a job's task group—for example, to only list the tasks that have successfully finished running—you must use the gcloud CLI or Batch API.
Console
To view a summary of a job's tasks using the Google Cloud console, view the details of a job to open the Job details page. Then, see the Task details section.
gcloud
To view a list of the tasks in a job's tasks group using the
gcloud CLI, use the
gcloud batch tasks list
command
with the following flags:
gcloud batch tasks list \
--job=JOB_NAME \
--location=LOCATION
Replace the following:
JOB_NAME
: the name of an existing job.LOCATION
: the location where the job exists.
Optionally, you can add the --filter
flag to view a filtered list of tasks
in a job's task group based on a filter expression.
For example, use the following command:
gcloud batch tasks list \
--job=example-job \
--location=us-central1 \
--filter="FILTER_EXPRESSION"
Replace FILTER_EXPRESSION
with a
filter expression.
For example, you can specify the following filter expression to only view the tasks in a job's task group that are running or have successfully finished running:
STATE=RUNNING OR STATE=SUCCEEDED
API
To view a list of tasks in a job's task group using the
Batch API, make a GET
request to the
tasks.list
method:
GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME/taskGroups/TASK_GROUP_NAME/tasks
Replace the following:
PROJECT_ID
: the project ID of the current project.LOCATION
: the location where the job exists.JOB_NAME
: the name of an existing job.TASK_GROUP_NAME
: the name of the task group that you want to view the details of. The value must be set togroup0
.
Optionally, you can specify the filter
query parameter to view a filtered
list of tasks in a job's task group based on a filter expression.
For example, make the following GET
request:
GET https://batch.googleapis.com/v1/projects/example-project/locations/us-central1/jobs/example-job/taskGroups/group0/tasks?filter=FILTER_EXPRESSION
Replace FILTER_EXPRESSION
with a
filter expression that uses
URL-encoding.
For example, you can specify the following filter expression to only view the tasks in a job's task group that are running or have successfully finished running:
STATE=RUNNING%20OR%20STATE=SUCCEEDED
Note that the URL-encoded filter expression represents the following decoded filter expression:
STATE=RUNNING OR STATE=SUCCEEDED
Go
Go
For more information, see the Batch Go API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
For more information, see the Batch Java API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Node.js
For more information, see the Batch Node.js API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
For more information, see the Batch Python API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C++
C++
For more information, see the Batch C++ API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
View the details of a task
You can view the details of a task using the Google Cloud console, gcloud CLI, Batch API, Go, Java, Node.js, Python, or C++.
Console
To view the details of a task using the Google Cloud console, view the details of a job to open the Job details page. Then, see the Task details section.
gcloud
To view the details of a task using the gcloud CLI, use the
gcloud batch tasks describe
command
with the following flags:
gcloud batch tasks describe TASK_INDEX \
--location=LOCATION \
--job=JOB_NAME \
--task_group=TASK_GROUP_NAME
Replace the following:
TASK_INDEX
: the index of the task that you want to view the details of. In a task group, the task index starts at 0 for the first task and increases by 1 with each additional task. For example, a task group that contains four tasks has the indexes0
,1
,2
, and3
.TASK_GROUP_NAME
: the name of the task group that contains the task that you want to view the details of. The value must be set togroup0
.JOB_NAME
: the name of an existing job.LOCATION
: the location where the job exists.
API
To view the details of a task using the Batch API, make a
GET
request to the
tasks.get
method:
GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME/taskGroups/TASK_GROUP_NAME/tasks/TASK_INDEX
Replace the following:
PROJECT_ID
: the project ID of the current project.LOCATION
: the location where the job exists.JOB_NAME
: the name of an existing job.TASK_GROUP_NAME
: the name of the task group that contains the task that you want to view the details of. The value must be set togroup0
.TASK_INDEX
: the index of the task that you want to view the details of. In a task group, the task index starts at 0 for the first task and increases by 1 with each additional task. For example, a task group that contains four tasks has the indexes0
,1
,2
, an,3
.
Go
Go
For more information, see the Batch Go API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
Java
For more information, see the Batch Java API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Node.js
Node.js
For more information, see the Batch Node.js API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
Python
For more information, see the Batch Python API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C++
C++
For more information, see the Batch C++ API reference documentation.
To authenticate to Batch, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
What's next
Learn about troubleshooting.
Learn how to monitor and analyze jobs:
If you configured logs for a job, you can analyze a job by using logs.
If you've configured status notifications, you can monitor a job using Pub/Sub notifications and analyze notifications using BigQuery.
Learn how to manage jobs: