# Get Job Status

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 %}

## Search job information

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

## Get bulk job status

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

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

#### Query parameter

| Attribute | Description                                     | Required |
| --------- | ----------------------------------------------- | -------- |
| bulkId    | `string` The bulk ID of the jobs to search for. | **Yes**  |

#### Response parameters

| 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.                                                           |

### Request example

The following request checks the status of the job specified in the request.

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

### Response example

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

## Get jobs based on user

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

Search jobs based on user permissions and ownership.

#### Query parameters

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

#### Response parameters

| Attribute | Description                                                             |
| --------- | ----------------------------------------------------------------------- |
| jobs      | `array` List of job objects containing job details.                     |
| next      | `string` Nullable string for pagination to get the next set of results. |

### Request example

The following request finds jobs in Immuta based on the requesting user's privileges.

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

### Response example

```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"
}
```

## Get a summary of jobs based on user

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

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

#### Query parameters

| Attribute | Description                                  | Required |
| --------- | -------------------------------------------- | -------- |
| jobType   | `array` List of job types to filter by.      | No       |
| startDate | `string` The start date to filter jobs from. | No       |
| endDate   | `string` The end date to filter jobs to.     | No       |

#### Response parameters

| Attribute | Description                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------- |
| jobType   | `array` Details about each job type, including the number of jobs in each state for each job type. |

### Request example

The following request finds jobs in Immuta based on the requesting user's privileges.

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

### Response example

```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
  }
}
```

## Get job status and output

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

Get the status and output of the provided jobs.

#### Payload parameters

| Attribute    | Description                                                                                                                                     | Required |
| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| jobIds       | `array` List of job IDs.                                                                                                                        | **Yes**  |
| wait         | `integer` Number of seconds to wait before returning if all jobs have not yet completed. Use `-1` to wait indefinitely. **The default is `0`.** | No       |
| pollInterval | `integer` Number of seconds to wait between subsequent polls. Ignored if not using `wait`. **The default is `1`. The minimum is `1`.**          | No       |

#### Response parameters

| 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.                                                           |

### Request example

The following request checks the status of the job specified in the payload.

```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 example

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

### Response example

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