> For the complete documentation index, see [llms.txt](https://documentation.immuta.com/saas/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/jobs.md).

# Get Job Status

Understand the parameters and response schema of the jobs endpoints

This page describes the `jobs` endpoint.

{% hint style="info" %}
Additional fields may be included in some responses you receive; however, these attributes are for internal purposes and are therefore undocumented.
{% endhint %}

## Endpoints and methods

| Method   | Endpoint                                | Description                                          |
| -------- | --------------------------------------- | ---------------------------------------------------- |
| **GET**  | [`/jobs`](#get-jobs)                    | Get bulk job status for a given job type and ID.     |
| **GET**  | [`/jobs/search`](#get-jobs-search)      | Search jobs based on user permissions and ownership. |
| **GET**  | [`/jobs/summary`](#get-jobs-summary)    | Get a summary of jobs based on user.                 |
| **POST** | [`/jobs/statuses`](#post-jobs-statuses) | Get job status and output.                           |

## <mark style="color:green;">`GET`</mark> `/jobs`

Gets the bulk job status for a given job type and ID.

```bash
curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://your-immuta-url.com/jobs?bulkId=example-bulk-id
```

### Query parameter

| Parameter           | Description                            | Required or optional |
| ------------------- | -------------------------------------- | -------------------- |
| **bulkId** `string` | The bulk ID of the jobs to search for. | Required             |

### Response

Returns the status of the requested jobs.

```json
{
  "cefb58a0-cd71-11ec-8e29-81c20d280994": {
  "id": "cefb58a0-cd71-11ec-8e29-81c20d280994",
  "state": "completed",
  "output": null
  }
}
```

#### Response attributes

| Attribute           | Description                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| **id** `string`     | The job's globally unique identifier.                                                          |
| **state** `string`  | The job state: `active`, `cancelled`, `completed`, `created`, `expired`, `failed`, or `retry`. |
| **output** `string` | The output of the job, if it exists.                                                           |

## <mark style="color:green;">`GET`</mark> `/jobs/search`

Search jobs based on user permissions and ownership.

```bash
curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://your-immuta-url.com/jobs/search
```

#### Query parameters

| Parameter              | Description                                                                                                 | Required or optional |
| ---------------------- | ----------------------------------------------------------------------------------------------------------- | -------------------- |
| **jobType** `array`    | List of job types to filter by.                                                                             | Optional             |
| **state** `string`     | The job state to filter by: `active`, `cancelled`, `completed`, `created`, `expired`, `failed`, or `retry`. | Optional             |
| **startDate** `string` | The start date to filter jobs from.                                                                         | Optional             |
| **endDate** `string`   | The end date to filter jobs to.                                                                             | Optional             |
| **offset** `integer`   | The number of results to skip for pagination.                                                               | Optional             |
| **size** `integer`     | The maximum number of results to return.                                                                    | Optional             |

### Response

Returns a list of [job objects](#job-object-attributes).

```json
{
  "jobs": [
  {
    "id": "1234124123123",
    "name": "policySync",
    "state": "active",
    "createdon": "2022-06-02T17:37:24.515Z",
    "startedon": "2023-06-02T17:37:24.515Z",
    "data": {},
    "output": {}
  }
  ],
  "next": "2"
}
```

## <mark style="color:green;">`GET`</mark> `/jobs/summary`

Get a summary of jobs based on user permissions and ownership.

```bash
curl \
  --request GET \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  https://your-immuta-url.com/jobs/summary
```

#### Query parameters

| Parameter              | Description                         | Required or optional | Accepted values                                                                                                                                                                     |
| ---------------------- | ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **jobType** `array`    | List of job types to filter by.     | Optional             | <ul><li><code>updatePolicies</code></li><li><code>updateDataPolicies</code></li><li><code>updateSubscriptionPolicies</code></li><li><code>createPolicySearchRecord</code></li></ul> |
| **startDate** `string` | The start date to filter jobs from. | Optional             | -                                                                                                                                                                                   |
| **endDate** `string`   | The end date to filter jobs to.     | Optional             | -                                                                                                                                                                                   |

### Response

Returns a detailed list of job status organized by job type.

```json
{
  "ingestCsv": {
  "pending": 2,
  "inProgress": 1,
  "completed": 45,
  "retry": 0,
  "failed": 3,
  "expired": 0,
  "cancelled": 1
  },
  "policySync": {
  "pending": 0,
  "inProgress": 0,
  "completed": 150,
  "retry": 1,
  "failed": 0,
  "expired": 0,
  "cancelled": 0
  },
  "dataMaskingUpdate": {
  "pending": 1,
  "inProgress": 2,
  "completed": 8,
  "retry": 0,
  "failed": 1,
  "expired": 0,
  "cancelled": 0
  }
}
```

## <mark style="color:green;">`POST`</mark> `/jobs/statuses`

Get the status and output of the provided jobs.

```bash
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer dea464c07bd07300095caa8" \
  --data @example_payload.json \
  https://your-immuta-url.com/jobs/statuses
```

**Payload**

```json
{
  "jobIds": [
    "cefb58a0-cd71-11ec-8e29-81c20d280994"
  ],
  "wait": 0,
  "pollInterval": 1
}
```

#### Body parameters

| Parameter                  | Description                                                                                                   | Required or optional | Default values | Accepted values    |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------- | -------------- | ------------------ |
| **jobIds** `array`         | List of job IDs.                                                                                              | Required             | -              | -                  |
| **wait** `integer`         | Number of seconds to wait before returning if all jobs have not yet completed. Use `-1` to wait indefinitely. | Optional             | `0`            | -                  |
| **pollInterval** `integer` | Number of seconds to wait between subsequent polls. Ignored if not using `wait`.                              | Optional             | `1`            | The minimum is `1` |

### Response

Returns the state and output for the requested jobs.

```json
{
  "cefb58a0-cd71-11ec-8e29-81c20d280994": {
    "id": "cefb58a0-cd71-11ec-8e29-81c20d280994",
    "state": "completed",
    "output": null
  }
}
```

## Job object attributes

| Attribute                 | Description                                                                                                    |
| ------------------------- | -------------------------------------------------------------------------------------------------------------- |
| **id** `string`           | The job's globally unique identifier.                                                                          |
| **name** `string`         | The internal job type or queue name associated with the job.                                                   |
| **state** `string`        | The job state: `active`, `cancelled`, `completed`, `created`, `expired`, `failed`, or `retry`.                 |
| **createdon** `timestamp` | The date and time when the job was created or queued.                                                          |
| **startedon** `timestamp` | The date and time when execution of the job started. This value may be unavailable if the job has not started. |
| **data** `object`         | The input payload and execution context of the job.                                                            |
| **output** `object`       | The output of the job, if it exists.                                                                           |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://documentation.immuta.com/saas/developer-guides/api-intro/immuta-v1-api/configure-your-instance-of-immuta/jobs.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.