This document explains how to view status events for Batch
jobs and tasks. Status events provide a history that you can use to analyze
jobs and often contain useful error messages that you can use for
troubleshooting.

Each job and each of its tasks have status events that are automatically
created by Batch while the job runs.
Each of these status events describe a state
change and details about why that state was reached.
To learn about job and task states, see
[Job lifecycle](https://docs.cloud.google.com/batch/docs/create-run-job#lifecycle).
Optionally, you can also configure a job to have custom status events, which
describe the progress of runnables.
To learn more about custom status events, see
[Configure custom status events](https://docs.cloud.google.com/batch/docs/create-run-job-custom-status-events).

## Before you begin

1. If you haven't used Batch before, review [Get started with Batch](https://docs.cloud.google.com/batch/docs/get-started) and enable Batch by completing the [prerequisites for projects and users](https://docs.cloud.google.com/batch/docs/get-started#prerequisites).
2.

   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](https://docs.cloud.google.com/iam/docs/granting-changing-revoking-access).


   You might also be able to get
   the required permissions through [custom
   roles](https://docs.cloud.google.com/iam/docs/creating-custom-roles) or other [predefined
   roles](https://docs.cloud.google.com/iam/docs/roles-overview#predefined).

<br />

## View status events

Different status events might appear at the job level
([`statusEvents[]` field for the job](https://docs.cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs#JobStatus.FIELDS.status_events))
and task level
([`statusEvents[]` field for each task](https://docs.cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs.taskGroups.tasks#TaskStatus.FIELDS.status_events)).

The following instructions explain how to view status events using the
Google Cloud console, gcloud CLI, and Batch API.
To use a client-library language, follow the steps to
[view the details of a job](https://docs.cloud.google.com/batch/docs/view-jobs-tasks#describe-job) or
[view the details of a task](https://docs.cloud.google.com/batch/docs/view-jobs-tasks#describe-task)
and then see the corresponding `statusEvents[]` field.

### View the status events of a job

### Console

> [!NOTE]
> **Note:** The Google Cloud console only lists job-level status events.

To view the status events of a job in the current project using the
Google Cloud console, follow these steps:

1. In the Google Cloud console, go to the **Job list** page.

   [Go to Job list](https://console.cloud.google.com/batch/jobs)
2. In the **Job name** column, click the name of a job.

   The **Job details** page opens.

   The **Details** tab is open by default.
3. Click the **Events** tab.

### gcloud

To view the status events of a job using the
gcloud CLI, use the
[`gcloud batch jobs describe` command](https://docs.cloud.google.com/sdk/gcloud/reference/batch/jobs/describe),
and then see the `statusEvents[]` field.

    gcloud batch jobs describe JOB_NAME \
        --location=LOCATION

Replace the following:

- `JOB_NAME`: the name of an existing job.

- `LOCATION`: the [location](https://docs.cloud.google.com/batch/docs/locations)
  where the job exists.

### API

To view the status events of a job using the
Batch API, make a `GET` request to the
[`jobs.get` method](https://docs.cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs/get),
and then see the `statusEvents[]` field.

    GET https://batch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/jobs/JOB_NAME

Replace the following:

- `PROJECT_ID`: the
  [project ID](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)
  of the current project.

- `LOCATION`: the [location](https://docs.cloud.google.com/batch/docs/locations)
  where the job exists.

- `JOB_NAME`: the name of an existing job.

### View the status events of a task

### gcloud

To view the status events of a task using the gcloud CLI, use the
[`gcloud batch tasks describe` command](https://docs.cloud.google.com/sdk/gcloud/reference/batch/tasks/describe),
and then see the `statusEvents[]` field.

    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 indexes `0`, `1`, `2`, and `3`.

- `JOB_NAME`: the name of an existing job.

- `LOCATION`: the [location](https://docs.cloud.google.com/batch/docs/locations) where
  the job exists.

- `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 to [`group0`](https://docs.cloud.google.com/batch/docs/get-started#restrictions).

### API

To view the status events of a task using the Batch API,
make a `GET` request to the
[`tasks.get` method](https://docs.cloud.google.com/batch/docs/reference/rest/v1/projects.locations.jobs.taskGroups.tasks/get),
and then see the `statusEvents[]` field.

    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](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects#identifying_projects)
  of the current project.

- `LOCATION`: the [location](https://docs.cloud.google.com/batch/docs/locations)
  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 to [`group0`](https://docs.cloud.google.com/batch/docs/get-started#restrictions).

- `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 indexes `0`, `1`, `2`, and `3`.

## What's next

- To understand status events from Batch that describe errors, see
  [Troubleshooting](https://docs.cloud.google.com/batch/docs/troubleshooting).

- If you want a more detailed history for your job, such as status events
  for when runnables start and end,
  [configure custom status events](https://docs.cloud.google.com/batch/docs/create-run-job-custom-status-events).

- Learn how to
  [analyze a job by using logs](https://docs.cloud.google.com/batch/docs/analyze-job-using-logs).