---
title: "GET | Listar um job do IAM por [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 | Listar um job do IAM por [id]

## Descrição

Leia o estado e o resultado de um job em segundo plano iniciado por um endpoint do IAM na plataforma Segura™. Endpoints que não conseguem responder de imediato retornam `202 Accepted` com um descritor de job, e este endpoint reporta o que aconteceu com esse job.

Nesta versão, o único tipo de job é o teste de conexão de servidor LDAP iniciado por [POST | Testar conexão do servidor LDAP por [id]](/v4-2/docs/api-v2-post-test-ldap-server-connection).

---

## Pré-requisitos

- Uma aplicação com a autorização **Users** concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A](/v4-2/docs/how-to-manage-authorizations-in-a2a).
- Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- O job deve ter sido iniciado pela mesma aplicação ou pelo mesmo usuário que faz esta requisição.

---

## Requisição

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

### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | string | Sim | Código de identificação único do job, no formato UUID. **Nota:** este valor é retornado no cabeçalho `Location` e em `data.job.id` pelo endpoint que iniciou o job. |

---

### Exemplo de requisição

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

---

## Resposta

```
HTTP/1.1 200 OK
```

### Exemplo de corpo da resposta

Um job que terminou com sucesso:

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

Um job que falhou:

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

---

## Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | O job. |
| `data.id` | string | Código de identificação único do job, no formato UUID. |
| `data.type` | string | Tipo do job. Retorna `ldap.test_connection` para um teste de conexão. |
| `data.state` | string | Estado do job. Veja [Estados do job](/docs/pt/api-v2-get-list-an-iam-job#estados-do-job). |
| `data.retry_count` | integer | Número de vezes que o job foi reexecutado. |
| `data.created_at` | datetime | Data e hora de criação do job. |
| `data.started_at` | datetime | Data e hora em que um worker começou a processar o job. Retorna `null` enquanto o job está na fila. |
| `data.finished_at` | datetime | Data e hora de finalização do job. Retorna `null` até então. |
| `data.result` | object | Resultado do job. Retornado apenas quando `state` é `succeeded`, e seus campos dependem do tipo de job. |
| `data.error` | object | Motivo da falha do job. Retornado apenas quando `state` é `failed`. |
| `data.error.code` | string | Código que identifica a falha. |
| `data.error.message` | string | Descrição da falha. |
| `meta` | object | Metadados do recurso. |
| `meta.links` | object | Links de navegação para o job. |
| `meta.links.self` | string | Caminho do job. |

### Estados do job

| Estado | Descrição |
| --- | --- |
| `queued` | O job aguarda um worker. |
| `running` | Um worker está processando o job. |
| `succeeded` | O job terminou e `result` contém o resultado. |
| `failed` | O job terminou com um erro e `error` contém o motivo. Um job com falha pode ser reexecutado com [POST \| Reexecutar um job do IAM por [id]](/v4-2/docs/api-v2-post-retry-an-iam-job). |

              Atenção

              

Os jobs são mantidos por 24 horas após a criação. Uma requisição para um job mais antigo que isso retorna `404 api.resource.not_found`, então leia o resultado antes que a janela se encerre.

Um job é visível para a aplicação que o iniciou e para o usuário que o iniciou. Uma requisição de outro usuário por meio de outra aplicação retorna `404 api.resource.not_found`, e não `403 Forbidden`.

---

## Erros

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `401` | `api.auth.unauthorized` | O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. |
| `404` | `api.resource.not_found` | O job não existe, tem mais de 24 horas ou foi iniciado por outro usuário por meio de outra aplicação. | Verifique o código de identificação e envie a requisição com a aplicação ou o usuário que iniciou o job. |
| `429` | `api.rate_limit.exceeded` | O limite de requisições foi excedido. | Reduza a frequência de requisições e tente novamente. |

Para mensagens de erros de autenticação e a política de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors).