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

# Consultar status do job batch

> Polling de status e contadores de um job de importação batch por jobId (entidades, transações e user events).

## Endpoint

```
GET https://api.gu1.ai/batch-import/jobs/{jobId}
```

Use esta rota como **endpoint canônico de polling** após qualquer upload bulk que retorne `202` com um `jobId`. Resolve o tipo de job automaticamente e faz lookup direto — **não** percorre o histórico completo.

## Autenticação

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Requer pelo menos um de: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`**.

## Query parameters

| Parâmetro | Descrição                                                                                                                                                                                    |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `include` | Lista CSV opcional. Use `include=failures` para obter o mesmo JSON do endpoint de failures por tipo (`failures[]`, `skips[]` em entidades, etc.). Omita para payload leve durante o polling. |

## Respostas HTTP

| Status | Quando                                           |
| ------ | ------------------------------------------------ |
| `200`  | Job encontrado                                   |
| `401`  | Não autenticado                                  |
| `403`  | Sem permissão de batch-import                    |
| `404`  | `jobId` desconhecido ou job de outra organização |

## Fluxo de polling recomendado

1. Upload (entidades, transações ou user events) → guardar `jobId` do `202`.
2. Poll `GET /batch-import/jobs/{jobId}` a cada **2–5 segundos**.
3. Parar quando `status` for terminal: `completed`, `failed`, `cancelled` ou `interrupted`.
4. Se precisarem de detalhe linha a linha, chamar com `?include=failures` ou usar o endpoint de failures por tipo (ver [Bulk imports overview](/pt/api-reference/bulk-imports/overview)).

<Note>
  Para listar jobs recentes (estilo dashboard), use [Unified history](/pt/api-reference/bulk-imports/list-unified-history). Para polling de um job específico, prefira este endpoint.
</Note>

## JSON (default — só status)

```json theme={null}
{
  "success": true,
  "job": {
    "jobId": "550e8400-e29b-41d4-a716-446655440000",
    "kind": "entity_automatic",
    "status": "running",
    "totalItems": 100,
    "succeeded": 45,
    "failed": 2,
    "skipped": 1,
    "heartbeatAt": "2026-06-26T12:00:00.000Z",
    "leaseExpiresAt": "2026-06-26T12:10:00.000Z",
    "workerError": null,
    "createdAt": "2026-06-26T11:59:00.000Z",
    "completedAt": null,
    "metadata": { "fileName": "entities.csv" }
  }
}
```

<ResponseField name="success" type="boolean">Sempre `true` quando o job existe.</ResponseField>

<ResponseField name="job.jobId" type="string">Identificador do job retornado no upload.</ResponseField>

<ResponseField name="job.kind" type="string">`entity_automatic`, `transaction_batch` ou `user_event_batch`.</ResponseField>

<ResponseField name="job.status" type="string">`queued`, `running`, `completed`, `failed`, `cancelled` ou `interrupted`. Durante cancelamento pode permanecer em `running` com `metadata.batchCancelRequested`.</ResponseField>

<ResponseField name="job.totalItems" type="number | null">Total de linhas/itens do job.</ResponseField>

<ResponseField name="job.succeeded" type="number | null">Quantidade processada com sucesso.</ResponseField>

<ResponseField name="job.failed" type="number | null">Quantidade de linhas com falha.</ResponseField>

<ResponseField name="job.skipped" type="number | null">Quantidade ignorada (ex.: taxId duplicado em entidades).</ResponseField>

<ResponseField name="job.heartbeatAt" type="string | null">Último heartbeat do worker (ISO 8601).</ResponseField>

<ResponseField name="job.leaseExpiresAt" type="string | null">Expiração do lease do worker (ISO 8601).</ResponseField>

<ResponseField name="job.workerError" type="string | null">Erro do worker truncado quando o job falhou em nível de job.</ResponseField>

<ResponseField name="job.createdAt" type="string">Criação do job (ISO 8601).</ResponseField>

<ResponseField name="job.completedAt" type="string | null">Conclusão quando terminal (ISO 8601).</ResponseField>

<ResponseField name="job.metadata" type="object | null">Metadata do job (ex.: `fileName`, modo de import).</ResponseField>

<ResponseField name="job.jobFailure" type="object | null">Presente quando `status` é `failed` e o job inteiro abortou. Inclui `code` estável e `message` — ver [Failure codes](/pt/api-reference/bulk-imports/batch-import-failure-codes).</ResponseField>

## JSON com `?include=failures`

Mesmo contrato dos endpoints JSON de failures por tipo:

* Entidades: [Entity batch failures](/pt/api-reference/bulk-imports/get-entity-batch-failures)
* Transações: [Transaction batch failures](/pt/api-reference/bulk-imports/get-transaction-batch-failures)
* User events: [User-event batch failures](/pt/api-reference/bulk-imports/get-user-event-batch-failures)

Sem falhas por linha, `failures` é array vazio (`failuresTotal: 0`).

Ver também: [Bulk imports overview](/pt/api-reference/bulk-imports/overview), [Unified history](/pt/api-reference/bulk-imports/list-unified-history).