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

Prerequisites

An application with the Users authorization granted by the administrator in A2A. For more information, access How to manage authorizations in A2A.
A valid OAuth 2.0 access token. For more information, access 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.
`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].

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.