Skip to main content
GET
/
batch-import
/
jobs
/
{jobId}
Consultar estado de 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}
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

Authorization: Bearer YOUR_API_KEY
Requiere al menos uno de: transactions:create, entities:bulk_import, events:create.

​
Query parameters

ParámetroDescripción
includeLista 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

StatusCuándo
200Job encontrado
401No autenticado
403Sin permiso de batch-import
404jobId 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).
Para listar jobs recientes (estilo dashboard), usen Unified history. Para polling de un job puntual, preferir este endpoint.

​
JSON (default — solo 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
Siempre true cuando el job existe.
​
job.jobId
string
Identificador del job devuelto en el upload.
​
job.kind
string
entity_automatic, transaction_batch o user_event_batch.
​
job.status
string
queued, running, completed, failed, cancelled o interrupted. Durante una cancelación puede seguir en running con metadata.batchCancelRequested.
​
job.totalItems
number | null
Total de filas/ítems del job.
​
job.succeeded
number | null
Cantidad procesada con éxito.
​
job.failed
number | null
Cantidad de filas fallidas.
​
job.skipped
number | null
Cantidad omitida (p. ej. taxId duplicado en entidades).
​
job.heartbeatAt
string | null
Último heartbeat del worker (ISO 8601).
​
job.leaseExpiresAt
string | null
Expiración del lease del worker (ISO 8601).
​
job.workerError
string | null
Error del worker truncado cuando el job falló a nivel job.
​
job.createdAt
string
Creación del job (ISO 8601).
​
job.completedAt
string | null
Finalización cuando es terminal (ISO 8601).
​
job.metadata
object | null
Metadata del job (p. ej. fileName, modo de import).
​
job.jobFailure
object | null
Presente cuando status es failed y abortó el job completo. Incluye code estable y message — ver Failure codes.

​
JSON con ?include=failures

Mismo contrato que los endpoints JSON de failures por tipo: Sin fallos por fila, failures es un array vacío (failuresTotal: 0). Ver también: Bulk imports overview, Unified history.