---
title: "GET | List an IAM job by [id]"
slug: "api-v2-get-list-an-iam-job"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-get-list-an-iam-job"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# GET | List an IAM job by [id]

## Description

Read the state and the result of a background job started by an IAM endpoint of the Segura™ platform. Endpoints that cannot answer immediately return `202 Accepted` with a job descriptor, and this endpoint reports what happened to that job.

In this version the only job type is the LDAP server connection test started by [POST | Test LDAP server connection by [id]](/v4-2/docs/api-v2-post-test-ldap-server-connection).

---

## Prerequisites

- An application with the **Users** authorization granted by the administrator in A2A. For more information, access [How to manage authorizations in A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- A valid OAuth 2.0 access token. For more information, access [How to authenticate an application in A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- The job must have been started by the same application or user making this request.

---

## Request

`GET` `/api/v2/iam/jobs/{id}`

### Path parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identification code of the job, in UUID format. **Note:** this value is returned in the `Location` header and in `data.job.id` by the endpoint that started the job. |

---

### Example request

`GET` `{{url}}/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8`

---

## Response

```
HTTP/1.1 200 OK
```

### Example response body

A job that finished successfully:

```
{
    "data": {
        "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
        "type": "ldap.test_connection",
        "state": "succeeded",
        "retry_count": 0,
        "created_at": "2026-05-08 23:52:25",
        "started_at": "2026-05-08 23:52:25",
        "finished_at": "2026-05-08 23:52:26",
        "result": {
            "bind_ok": true,
            "base_search_ok": true,
            "elapsed_ms": 312,
            "translated_host": "ad.example.com",
            "translated_port": 389
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8" }
    }
}
```

A job that failed:

```
{
    "data": {
        "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
        "type": "ldap.test_connection",
        "state": "failed",
        "retry_count": 0,
        "created_at": "2026-05-08 23:52:25",
        "started_at": "2026-05-08 23:52:25",
        "finished_at": "2026-05-08 23:52:30",
        "error": {
            "code": "api.ldap.test_connection.dc_unavailable",
            "message": "LDAP bind failed: Can't contact LDAP server"
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8" }
    }
}
```

---

## Response body fields

| Field | Type | Description |
| --- | --- | --- |
| `data` | object | The job. |
| `data.id` | string | Unique identification code of the job, in UUID format. |
| `data.type` | string | Type of job. Returns `ldap.test_connection` for a connection test. |
| `data.state` | string | State of the job. See [Job states](/docs/api-v2-get-list-an-iam-job#job-states). |
| `data.retry_count` | integer | Number of times the job was retried. |
| `data.created_at` | datetime | Date and time the job was created. |
| `data.started_at` | datetime | Date and time a worker picked the job up. Returns `null` while the job is queued. |
| `data.finished_at` | datetime | Date and time the job ended. Returns `null` until it ends. |
| `data.result` | object | Outcome of the job. Returned only when `state` is `succeeded`, and its fields depend on the job type. |
| `data.error` | object | Reason the job failed. Returned only when `state` is `failed`. |
| `data.error.code` | string | Code identifying the failure. |
| `data.error.message` | string | Description of the failure. |
| `meta` | object | Resource metadata. |
| `meta.links` | object | Navigation links for the job. |
| `meta.links.self` | string | Path of the job. |

### Job states

| State | Description |
| --- | --- |
| `queued` | The job is waiting for a worker. |
| `running` | A worker is processing the job. |
| `succeeded` | The job finished and `result` holds its outcome. |
| `failed` | The job finished with an error and `error` holds the reason. A failed job can be retried with [POST \| Retry an IAM job by [id]](/v4-2/docs/api-v2-post-retry-an-iam-job). |

              Attention

              

Jobs are kept for 24 hours after they are created. A request for a job older than that returns `404 api.resource.not_found`, so read the result before the window closes.

A job is visible to the application that started it and to the user who started it. A request from a different user through a different application returns `404 api.resource.not_found` rather than `403 Forbidden`.

---

## Errors

| HTTP code | Message | Possible cause | Solution |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | The access token is missing or has expired. | Request a new access token. |
| `404` | `api.resource.not_found` | The job does not exist, is older than 24 hours, or was started by a different user through a different application. | Check the identification code, and send the request with the application or the user that started the job. |
| `429` | `api.rate_limit.exceeded` | The request rate limit was exceeded. | Reduce the request rate and try again. |

For authentication error messages and the `403` versus `404` policy, access [API v2 - Conventions and shared behaviors](/v4-2/docs/api-v2-conventions-and-shared-behaviors).