Obtener el estado de un trabajo

GET/v1/jobs/{id}

Para desarrolladores

Descripción

Devuelve el estado de un trabajo en segundo plano: si espera su turno, se está ejecutando o terminó, y por qué falló si falló.

Importar un archivo en una lista, combinar listas y tomar la instantánea de un dataset responden el id del trabajo en job_id. Exportar una lista responde el trabajo mismo, y su archivo se descarga con GET /v1/jobs/{id}/file. Copiar una lista a un dataset también responde el trabajo mismo.

Autenticación

Authorizationbearer tokenheaderobligatorio

Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Scope requerido: el de lectura del recurso sobre el que trabaja. Los trabajos de listas (list_import, list_merge, list_snapshot, list_export, list_copy) piden list:read.

Request

Path params:

idstring (UUID)obligatorio

Identificador del trabajo.

Response

200 OKDevuelve un objeto con los campos que siguen.

idstring (UUID)siempre presente

Identificador del trabajo.

typestring, enum: `list_import | list_merge | list_snapshot | list_export | list_copy`siempre presente

Qué hace el trabajo: list_import importa un archivo en una lista, list_merge combina listas en una nueva, list_snapshot toma la instantánea de un dataset en una lista nueva, list_export exporta los datos de una lista a un CSV y list_copy copia los contactos de una lista a un dataset.

statusstring, enum: `pending | processing | completed | failed`siempre presente

pending mientras espera su turno, processing mientras se ejecuta, y completed o failed al terminar.

paramsobjectsiempre presente

Sobre qué trabaja. En los trabajos de listas, list_id e import_id: la lista que recibe los datos y su importación. En list_copy, list_id e import_id son la lista de origen y su importación, y se suman dataset_id (el dataset de destino) y rate_per_minute, el máximo de contactos por minuto de la copia: la tasa que tenía el dataset al pedirla, compartida con la API.

resultobject | null

El resultado del trabajo, según su tipo (type). En list_export, el archivo: row_count (filas), size_bytes (tamaño en bytes), expires_at (hasta cuándo se puede descargar) y, una vez borrado, purged_at. En list_copy, los conteos de la copia (ver Copiar una lista a un dataset). Mientras la copia se ejecuta, muestra lo enviado hasta ese momento y next_row, la primera fila que falta enviar. En list_import, list_merge y list_snapshot es null: el resultado está en su importación (import_id de params).

error_codestring | null

Código del error, si falló (ver Notas de GET /v1/jobs/{id}).

error_messagestring | null

Por qué falló, si falló (en inglés).

created_atstring (date-time)siempre presente

Cuándo se creó el trabajo (ISO 8601, UTC).

started_atstring (date-time) | null

Cuándo empezó su último intento.

finished_atstring (date-time) | null

Cuándo terminó, haya completado o fallado.

Errores

Código	Cuándo
404	El trabajo no existe, o la API key no tiene el scope de lectura de su recurso (job_not_found).
422	id no es un UUID.

Notas

• Para seguir un trabajo, consulte esta URL cada algunos segundos hasta que status sea completed o failed.
• Los contadores de una importación están en la importación. Un trabajo de listas dice si terminó y por qué falló; cuántas filas quedaron y cuántas se descartaron lo responde GET /v1/lists/{list_id}/imports/{import_id}, con los ids de params.
• error_code en un trabajo de importación de listas es, en general, el código de su importación (ver la tabla en GET /v1/lists/{id}/imports/{import_id}).
• Una exportación falla con list_not_found (la lista se eliminó), list_export_source_missing (sus datos no están disponibles), list_export_no_space (no hubo espacio para escribir el archivo: vuelva a pedirla más tarde) o list_export_internal_error.
• Una copia a un dataset falla con list_copy_source_missing (los datos de la lista no están disponibles), list_copy_dataset_missing (el dataset se eliminó), list_identity_field_missing o dataset_required_column_missing (el dataset cambió sus columnas después de pedir la copia), list_copy_no_valid_rows (ninguna fila es válida) o list_copy_internal_error.
• Los códigos siguientes son del trabajo y no de su recurso:

error_code	Cuándo
job_expired	La plataforma no lo terminó en su plazo: no empezó en un día, o lleva una hora sin avanzar. Vuelva a pedir la operación.
job_attempts_exhausted	Falló en cada intento sin un error propio. Suele deberse a un archivo demasiado grande para procesarlo. Con el mismo archivo vuelve a fallar: divídalo y vuelva a pedir la operación.
job_type_unknown	No se pudo ejecutar su tipo. Vuelva a pedir la operación.

Request

curl -X GET "https://$API_HOST/v1/jobs/01a13a48-9e05-7d41-9a8f-3c1d2e4f5a6b" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"id": "01a13a48-9e05-7d41-9a8f-3c1d2e4f5a6b",
"type": "list_import",
"status": "completed",
"params": {
  "list_id": 4,
  "import_id": 17
},
"result": null,
"error_code": null,
"error_message": null,
"created_at": "2026-10-14T12:00:00Z",
"started_at": "2026-10-14T12:00:02Z",
"finished_at": "2026-10-14T12:00:09Z"
}