Skip to main content
GET
/
batch-import
/
jobs
/
{jobId}
Consultar status do job batch
curl --request GET \
  --url http://api.gu1.ai/batch-import/jobs/{jobId} \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "job.jobId": "<string>",
  "job.kind": "<string>",
  "job.status": "<string>",
  "job.totalItems": {},
  "job.succeeded": {},
  "job.failed": {},
  "job.skipped": {},
  "job.heartbeatAt": {},
  "job.leaseExpiresAt": {},
  "job.workerError": {},
  "job.createdAt": "<string>",
  "job.completedAt": {},
  "job.metadata": {},
  "job.jobFailure": {}
}

​
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

Authorization: Bearer YOUR_API_KEY
Requer pelo menos um de: transactions:create, entities:bulk_import, events:create.

​
Query parameters

ParâmetroDescrição
includeLista 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

StatusQuando
200Job encontrado
401Não autenticado
403Sem permissão de batch-import
404jobId 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).
Para listar jobs recentes (estilo dashboard), use Unified history. Para polling de um job específico, prefira este endpoint.

​
JSON (default — só status)

{
  "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" }
  }
}
​
success
boolean
Sempre true quando o job existe.
​
job.jobId
string
Identificador do job retornado no upload.
​
job.kind
string
entity_automatic, transaction_batch ou user_event_batch.
​
job.status
string
queued, running, completed, failed, cancelled ou interrupted. Durante cancelamento pode permanecer em running com metadata.batchCancelRequested.
​
job.totalItems
number | null
Total de linhas/itens do job.
​
job.succeeded
number | null
Quantidade processada com sucesso.
​
job.failed
number | null
Quantidade de linhas com falha.
​
job.skipped
number | null
Quantidade ignorada (ex.: taxId duplicado em entidades).
​
job.heartbeatAt
string | null
Último heartbeat do worker (ISO 8601).
​
job.leaseExpiresAt
string | null
Expiração do lease do worker (ISO 8601).
​
job.workerError
string | null
Erro do worker truncado quando o job falhou em nível de job.
​
job.createdAt
string
Criação do job (ISO 8601).
​
job.completedAt
string | null
Conclusão quando terminal (ISO 8601).
​
job.metadata
object | null
Metadata do job (ex.: fileName, modo de import).
​
job.jobFailure
object | null
Presente quando status é failed e o job inteiro abortou. Inclui code estável e message — ver Failure codes.

​
JSON com ?include=failures

Mesmo contrato dos endpoints JSON de failures por tipo: Sem falhas por linha, failures é array vazio (failuresTotal: 0). Ver também: Bulk imports overview, Unified history.