Referencia de la API

Exportaciones

Una exportación genera un solo archivo con todos los leads que coinciden con tus filtros, para cuando hay demasiados leads para paginar. Créala, consúltala hasta que su status esté en ready y descarga su url. Puedes crear 10 exportaciones por hora por cuenta.

Con type en conversations, el archivo contiene en su lugar todas las conversaciones por DM de la cuenta, cada una con su lead y todos sus mensajes desde el primero. Está pensado para analizar tus DM en bloque, con un asistente de IA o con tu propio código, y ver qué mensaje de apertura consigue respuestas y qué respuesta ayuda a un lead a superar una objeción. Gemlead guarda su propia copia de todos tus DM sincronizada con X, ediciones y eliminaciones incluidas, así que el archivo se crea desde esa copia sin llamar a X y 1 500 conversaciones están listas en menos de un minuto.

Endpoints

POST/v1/exports
GET/v1/exports
GET/v1/exports/:id

El objeto export

Un archivo de leads o de conversaciones generado en segundo plano, para las extracciones grandes en las que paginar es demasiado lento.

Atributos

idstring
Identificador único de la exportación.
objectstring
Siempre export.
typestring
Lo que contiene el archivo, leads o conversaciones con sus mensajes.
leadsconversations
statusstring
processing mientras se genera el archivo, luego ready o failed. expired cuando su enlace ha caducado.
processingreadyfailedexpired
formatstring
El formato del archivo, csv o jsonl para leads, jsonl o markdown para conversaciones.
csvjsonlmarkdown
filtersobject
Los filtros con los que se creó la exportación, como en Listar leads o Listar conversaciones.
row_countinteger
Leads o conversaciones del archivo. La cifra crece mientras se genera el archivo. 100 000 leads o 20 000 conversaciones como máximo.
total_countinteger o null
En una exportación de conversaciones sin filtros, cuántas conversaciones tendrá el archivo, contadas al empezar a generarlo. null en los demás casos.
urlstring o null
Dónde descargar el archivo, una vez listo. Funciona durante 24 horas, hasta expires_at.
expires_atstring o null
Cuándo deja de funcionar url, en ISO 8601.
created_atstring
Cuándo se creó la exportación, en ISO 8601.

El objeto export

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Crear una exportación

POST/v1/exportsScope readMCPcreate_export

Empieza a generar un archivo de leads o de conversaciones. Responde al instante con la exportación en processing.

Parámetros del cuerpo

typestring
Qué exportar. leads por defecto.
leadsconversations
formatstring
El formato del archivo. Para leads, csv o jsonl, csv por defecto. Para conversaciones, jsonl o markdown, jsonl por defecto.
csvjsonlmarkdown
filtersobject
Los leads que exportar, con los filtros de Listar leads. Para conversaciones, solo persona y unread, como en Listar conversaciones.

Devuelve

Un objeto export con el estado processing y el código de estado HTTP 202.

Errores

400parameter_missing
Falta un parámetro obligatorio. param lo indica.
400parameter_invalid
Un parámetro tiene un valor que la API no acepta. param lo indica.
429export_rate_limit_exceeded
Más de 10 exportaciones en la última hora en la cuenta.

POST/v1/exports

curl -X POST https://gemlead.ai/api/v1/exports \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": {
      "hot": true,
      "persona": "lvWBPnytpS"
    }
  }'

Respuesta202

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "processing",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 0,
  "total_count": null,
  "url": null,
  "expires_at": null,
  "created_at": "2026-11-06T07:45:12.904Z"
}

Listar exportaciones

GET/v1/exportsScope readMCPlist_exports

Devuelve tus exportaciones, primero las más recientes.

Parámetros de consulta

limitinteger
Cuántos objetos devolver, de 1 a 100. 25 por defecto.
cursorstring
El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos export.

GET/v1/exports

curl https://gemlead.ai/api/v1/exports \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Respuesta200

{
  "object": "list",
  "data": [
    {
      "id": "e4TnW8yHqA",
      "object": "export",
      "type": "leads",
      "status": "ready",
      "format": "csv",
      "filters": {
        "hot": true,
        "persona": "lvWBPnytpS"
      },
      "row_count": 2134,
      "total_count": null,
      "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
      "expires_at": "2026-11-07T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Obtener una exportación

GET/v1/exports/:idScope readMCPget_export

Devuelve una exportación. Consúltala cada pocos segundos hasta que status esté en ready y luego descarga url.

Parámetros de ruta

idstringObligatorio
El ID de la exportación.

Devuelve

Un objeto export.

Errores

404resource_missing
No hay ninguna exportación con este ID en la cuenta de la clave.

GET/v1/exports/:id

curl https://gemlead.ai/api/v1/exports/e4TnW8yHqA \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Respuesta200

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Una conversación del archivo

Cada línea de un archivo jsonl de conversaciones, primero la conversación más reciente. Es el objeto conversation con su hilo completo, su lead y history. Un archivo markdown contiene lo mismo, con una transcripción por conversación.

Atributos

idstring
Identificador único de la conversación.
objectstring
Siempre conversation.
lead_idstring
El lead con el que hablas.
profileobject
El perfil de X del lead, como en el objeto lead.
personaobject o null
El buyer persona del lead.
columnobject o null
La columna de tu tablero de Conversaciones en la que está la conversación.
unreadboolean
True si el último mensaje del lead aún no se ha leído.
messages_countinteger
Mensajes en messages.
first_message_atstring o null
Cuándo se envió el primer mensaje, en ISO 8601.
last_message_atstring o null
Cuándo se envió el último mensaje, en ISO 8601.
last_messageobject o null
El último mensaje.
leadobject o null
El objeto lead, con su puntuación, su estado, su buyer persona y su campaña.
historystring
complete cuando messages es el hilo completo. recent mientras Gemlead solo guarda los últimos mensajes de un hilo largo, antes de leer el resto desde X una sola vez.
completerecent
messagesarray de objects
Todos los mensajes del hilo, primero los más antiguos, con su dirección, texto, fecha, adjuntos y reacciones. Los enlaces de los adjuntos funcionan durante 24 horas.

Una conversación del archivo

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "unread": false,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 1,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  },
  "first_message_at": "2026-11-06T08:12:44.000Z",
  "lead": {
    "id": "msgOtJ8dvT",
    "object": "lead",
    "profile": {
      "x_user_id": "1460283925",
      "username": "jane_builds",
      "name": "Jane Doe",
      "bio": "Runs a paid trading community. Daily setups, no hype.",
      "followers_count": 12400,
      "following_count": 380,
      "location": "Austin, TX",
      "website": "https://janedoe.com",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
      "verified": true,
      "url": "https://x.com/jane_builds"
    },
    "score": 86,
    "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
    "hot": true,
    "status": "scored",
    "persona": {
      "id": "lvWBPnytpS",
      "name": "Tipsters"
    },
    "campaign": null,
    "conversation_id": null,
    "locked_to": null,
    "found_at": "2026-11-05T14:02:11.482Z",
    "scored_at": "2026-11-05T14:03:40.117Z",
    "updated_at": "2026-11-05T14:03:40.117Z",
    "metadata": {}
  },
  "history": "complete",
  "messages": [
    {
      "id": "1985321409876543210",
      "object": "message",
      "direction": "inbound",
      "text": "Yes, I want to charge for my Discord. How does it work?",
      "created_at": "2026-11-06T08:12:44.000Z",
      "media": [],
      "reactions": [],
      "encrypted": false,
      "reply_to_message_id": null
    }
  ]
}