Saltar al contenido principal

Tomar una instantánea de un dataset

POST/v1/datasets/{id}/snapshot

Para desarrolladores

Descripción​

Toma una instantánea de un dataset (en el panel, Copiar a una lista): crea una lista nueva con los contactos que el dataset tiene en ese momento, una fila por contacto. El dataset no cambia y sigue recibiendo contactos; la lista queda fija, como cualquier otra, y registra de qué dataset salió en source_dataset_id.

La instantánea es la importación de la lista nueva: queda en cola y la respuesta llega antes de que se lean los contactos. El estado se consulta en la URL del header Location (GET /v1/lists/{id}/imports/{import_id}), igual que al subir un archivo. La lista guarda los contactos tal como estaban al leerlos: los que entren, se corrijan o se quiten después no la cambian.

La lista nueva:

  • Tiene todas las columnas que el dataset declara: primero la del campo por el que el dataset identifica a un contacto, que es obligatoria y única, y después las demás en el orden en que se declararon, con sus obligatorios. Una columna de un campo desactivado se incluye.
  • Su canal es el del dataset.
  • Los valores no se vuelven a validar contra las reglas de sus campos: ya las pasaron al entrar al dataset. Una fila sin el identificador, o con un valor que no corresponde al tipo de su columna, no pasa a la lista y se cuenta en failed_row_count.
  • Un contacto que el dataset tiene en más de una fila aparece una sola vez, con su fila actualizada más recientemente. Las demás se cuentan en duplicated_row_count.
  • La supresión, el consentimiento y el cupo del plan no se aplican aquí: se aplican al enviar.

Autenticación​

Authorizationbearer tokenheaderobligatorio
API key con los scopes dataset:read y list:write. Formato: Bearer <API_KEY>.
X-Instance-Slugstringheaderobligatorio
Identificador de su instancia. Ver Autenticación.

Request​

Path params:

idintegerobligatorio
Identificador del dataset. Puede estar inactivo.

Body (application/json):

namestringobligatorio
Nombre de la lista nueva. No puede ser el de otra lista vigente.
descriptionstring
Descripción de la lista nueva.

Response​

201 CreatedDevuelve el objeto creado. El header Location trae su URL (ver Headers).
idintegersiempre presente
Identificador de la importación.
list_idintegersiempre presente
Lista a la que pertenece.
job_idstring (UUID) | null
Trabajo que ejecuta la importación; su estado se consulta en GET /v1/jobs/{id}. null mientras la lista no declara sus columnas.
statusstring, enum: `awaiting_mapping | pending | processing | completed | failed`siempre presente
awaiting_mapping mientras la lista no declara sus columnas, pending mientras espera su turno, processing mientras se lee el archivo, y completed o failed al terminar.
file_namestring | null
Nombre que tenía el archivo al subirlo.
file_bytesinteger | null
Tamaño del archivo tal como se subió, en bytes.
encodingstring | null
Codificación del archivo: la detectada en sus primeras líneas hasta que se procesa, y después la que se decidió sobre el archivo completo (utf-8, utf-16, utf-32, cp1252).
delimiterstring | null
Separador de columnas: el indicado al subirlo o el detectado.
csv_row_countinteger | null
Filas leídas del archivo, sin contar la cabecera ni las filas en blanco. En una combinación, las leídas de las listas; en una instantánea, las del dataset. null hasta que se procesa.
imported_row_countinteger | null
Filas que quedaron en la lista. 0 si la importación falló.
failed_row_countinteger | null
Filas descartadas por un valor inválido, un campo obligatorio vacío, columnas de más o caracteres que no corresponden a la codificación.
duplicated_row_countinteger | null
Filas descartadas por repetir el valor de una columna única. En una combinación, las de un contacto que ya estaba en una lista anterior; en una instantánea, las filas más antiguas de un contacto que el dataset tiene repetido.
has_rejectsbooleansiempre presente
Si hay un archivo con las filas descartadas para descargar (GET /v1/lists/{id}/imports/{import_id}/rejects).
error_messagestring | null
Por qué falló la importación, si falló (en inglés).
diagnosticsobject | null
Detalle de la importación, descrito abajo.
encoding, format
La codificación con que se leyó el archivo y su formato: plain, gzip, zip o 7z. No están en una combinación ni en una instantánea.
source
En una instantánea: dataset_id, el dataset leído, y snapshot_at, el momento en que se leyó (UTC).
reasons
Filas descartadas por motivo. Cada fila cuenta una vez, con el primer motivo que encontró: invalid_character, extra_columns, required_missing, invalid_value o duplicated.
fields
Por field_key, cuántas filas tenían ese campo vacío siendo obligatorio, inválido o repetido. Una fila con dos campos inválidos cuenta en los dos.
repaired_rows / damaged_text_rows
Filas con texto dañado por una conversión de codificación anterior (José): reparadas si la lista tiene repair_encoding, o detectadas y cargadas tal cual si no.
error
Si la importación falló: code, y field o line cuando el problema tiene un lugar en el archivo.
source_listsobject[] | null
En una combinación (POST /v1/lists/merge), las listas que se combinaron, en orden. Cada una trae list_id e import_id, que es la importación de la que salieron sus datos. null en una importación de archivo o en una instantánea.
identity_fieldstring | null
En una combinación o en una instantánea, el campo que identifica a un contacto: EMAIL, PHONE o UNIQUECODE. null en una importación de archivo.
collision_policystring | null
En una combinación, cómo se resolvió un contacto que estaba en varias listas: discard, fill, update o replace. null en una importación de archivo o en una instantánea.
delete_sourcesboolean | null
En una combinación, si las listas de origen se eliminan al terminar. null en una importación de archivo o en una instantánea.
created_atstring (date-time)siempre presente
Cuándo se subió el archivo (ISO 8601, UTC).
started_atstring (date-time) | null
Cuándo empezó a leerse.
finished_atstring (date-time) | null
Cuándo terminó, haya completado o fallado.
Notas

Errores​

CódigoCuándo
403A la API key le falta dataset:read, list:write o los dos.
404El dataset no existe o fue eliminado (dataset_not_found).
409Ya existe una lista vigente con ese nombre (list_name_taken), o el dataset no declara la columna por la que identifica a un contacto (list_identity_field_missing).
422El body no es válido: name falta o viene vacío, o hay un campo que no existe.
503No se pudo dejar la instantánea en cola (service_unavailable). No queda nada creado: reintente.

Detalle completo en Errores genéricos.

Notas
  • Una instantánea que falla deja la lista nueva sin datos. Los códigos con que puede fallar están en GET /v1/lists/{id}/imports/{import_id}. Entre ellos, list_snapshot_too_large: un dataset de más de 15 millones de filas no admite una instantánea.
  • Una lista que salió de una instantánea solo recibe datos de su dataset: no acepta un archivo ni un cambio de columnas, aunque su instantánea haya fallado (409 list_is_snapshot). Para tener los contactos de nuevo, tome otra instantánea.
  • Un dataset sin contactos deja una lista con 0 filas.
  • csv_row_count es la cantidad de filas que tenía el dataset al leerlo: csv_row_count = imported_row_count + failed_row_count + duplicated_row_count. No hay archivo de rechazos: las filas que no pasaron siguen en el dataset, y diagnostics las cuenta por motivo y por campo.
Request
curl -X POST "https://$API_HOST/v1/datasets/8/snapshot" \
-H "Authorization: Bearer $API_KEY" \
-H "X-Instance-Slug: $SLUG" \
-H "Content-Type: application/json" \
-d '{
  "name": "Clientes al 16 de octubre"
}'
Response
{
"id": 32,
"list_id": 13,
"job_id": "01a14495-5603-7f15-b6c2-1a2b3c4d5e6f",
"status": "pending",
"file_name": null,
"file_bytes": null,
"encoding": null,
"delimiter": null,
"csv_row_count": null,
"imported_row_count": null,
"failed_row_count": null,
"duplicated_row_count": null,
"has_rejects": false,
"error_message": null,
"diagnostics": null,
"source_lists": null,
"identity_field": "EMAIL",
"collision_policy": null,
"delete_sources": null,
"created_at": "2026-10-16T12:00:00Z",
"started_at": null,
"finished_at": null
}