> ## 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 estado de job batch

> Polling del estado y contadores de un job de importación batch por jobId (entidades, transacciones y user events).

## Endpoint

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

Usen esta ruta como **endpoint canónico de polling** después de cualquier upload bulk que devuelva `202` con un `jobId`. Resuelve el tipo de job automáticamente y hace lookup directo — **no** recorre el histórico completo.

## Autenticación

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

Requiere al menos uno de: **`transactions:create`**, **`entities:bulk_import`**, **`events:create`**.

## Query parameters

| Parámetro | Descripción                                                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `include` | Lista CSV opcional. Usen `include=failures` para obtener el mismo JSON que el endpoint de failures por tipo (`failures[]`, `skips[]` en entidades, etc.). Omitan para un payload liviano durante el polling. |

## Respuestas HTTP

| Status | Cuándo                                         |
| ------ | ---------------------------------------------- |
| `200`  | Job encontrado                                 |
| `401`  | No autenticado                                 |
| `403`  | Sin permiso de batch-import                    |
| `404`  | `jobId` desconocido o job de otra organización |

## Flujo de polling recomendado

1. Upload (entidades, transacciones o user events) → guardar `jobId` del `202`.
2. Poll `GET /batch-import/jobs/{jobId}` cada **2–5 segundos**.
3. Detener cuando `status` sea terminal: `completed`, `failed`, `cancelled` o `interrupted`.
4. Si necesitan detalle fila a fila, llamar con `?include=failures` o usar el endpoint de failures por tipo (ver [Bulk imports overview](/es/api-reference/bulk-imports/overview)).

<Note>
  Para listar jobs recientes (estilo dashboard), usen [Unified history](/es/api-reference/bulk-imports/list-unified-history). Para polling de un job puntual, preferir este endpoint.
</Note>

## JSON (default — solo 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">Siempre `true` cuando el job existe.</ResponseField>

<ResponseField name="job.jobId" type="string">Identificador del job devuelto en el upload.</ResponseField>

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

<ResponseField name="job.status" type="string">`queued`, `running`, `completed`, `failed`, `cancelled` o `interrupted`. Durante una cancelación puede seguir en `running` con `metadata.batchCancelRequested`.</ResponseField>

<ResponseField name="job.totalItems" type="number | null">Total de filas/ítems del job.</ResponseField>

<ResponseField name="job.succeeded" type="number | null">Cantidad procesada con éxito.</ResponseField>

<ResponseField name="job.failed" type="number | null">Cantidad de filas fallidas.</ResponseField>

<ResponseField name="job.skipped" type="number | null">Cantidad omitida (p. ej. taxId duplicado en entidades).</ResponseField>

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

<ResponseField name="job.leaseExpiresAt" type="string | null">Expiración del lease del worker (ISO 8601).</ResponseField>

<ResponseField name="job.workerError" type="string | null">Error del worker truncado cuando el job falló a nivel job.</ResponseField>

<ResponseField name="job.createdAt" type="string">Creación del job (ISO 8601).</ResponseField>

<ResponseField name="job.completedAt" type="string | null">Finalización cuando es terminal (ISO 8601).</ResponseField>

<ResponseField name="job.metadata" type="object | null">Metadata del job (p. ej. `fileName`, modo de import).</ResponseField>

<ResponseField name="job.jobFailure" type="object | null">Presente cuando `status` es `failed` y abortó el job completo. Incluye `code` estable y `message` — ver [Failure codes](/es/api-reference/bulk-imports/batch-import-failure-codes).</ResponseField>

## JSON con `?include=failures`

Mismo contrato que los endpoints JSON de failures por tipo:

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

Sin fallos por fila, `failures` es un array vacío (`failuresTotal: 0`).

Ver también: [Bulk imports overview](/es/api-reference/bulk-imports/overview), [Unified history](/es/api-reference/bulk-imports/list-unified-history).