Listar trabajos

GET/v1/jobs

Para desarrolladores

Descripción

Devuelve los trabajos en segundo plano de la instancia, del más reciente al más antiguo.

Autenticación

Authorizationbearer tokenheaderobligatorio

Formato: Bearer <API_KEY>.

X-Instance-Slugstringheaderobligatorio

Identificador de su instancia. Ver Autenticación.

Cada trabajo exige el scope de lectura de su recurso: los de listas (list_import, list_merge, list_snapshot, list_export, list_copy) piden list:read, y una API key sin él no los ve.

Request

Query params:

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

Solo los trabajos de este tipo.

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

Solo los trabajos en este estado.

pageinteger

Número de página; la primera es la 1. Default: 1.

page_sizeinteger

Tamaño de página, 1–100. Default: 20.

Response

200 OKCada elemento de data es un trabajo, con los campos de GET /v1/jobs/{id}.

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.

Notas

• La paginación no informa el total: pagination.has_more dice si hay una página siguiente, y total_items y total_pages vienen en null.
• Los trabajos que la API key no puede leer no aparecen, y tampoco cuentan para has_more.

Request

curl -X GET "https://$API_HOST/v1/jobs?type=list_import&status=failed" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG"

Response

{
"data": [
  {
    "id": "01a13f6e-fa08-7e2a-8b3d-5f6a7b8c9d0e",
    "type": "list_merge",
    "status": "processing",
    "params": {
      "list_id": 12,
      "import_id": 31
    },
    "result": null,
    "error_code": null,
    "error_message": null,
    "created_at": "2026-10-15T12:00:00Z",
    "started_at": "2026-10-15T12:00:01Z",
    "finished_at": null
  }
],
"pagination": {
  "page": 1,
  "page_size": 20,
  "has_more": false,
  "total_items": null,
  "total_pages": null
}
}