Riferimento API

Export

Un export crea un solo file con tutti i lead che corrispondono ai tuoi filtri, per le estrazioni troppo grandi da paginare. Crealo, poi recuperalo finché il suo status è ready e scarica il suo url. Puoi creare 10 export all'ora per account.

Con type impostato su conversations, il file contiene invece tutte le conversazioni in DM dell'account, ognuna con il suo lead e tutti i messaggi dal primo. Serve a studiare i tuoi DM in blocco, con un assistente IA o con il tuo codice, per capire quale messaggio di apertura ottiene risposte e quale risposta aiuta un lead a superare un'obiezione. Gemlead conserva una propria copia di tutti i tuoi DM sincronizzata con X, modifiche ed eliminazioni comprese, quindi il file viene creato da quella copia senza chiamare X e 1 500 conversazioni sono pronte in meno di un minuto.

Endpoint

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

L'oggetto export

Un file di lead o di conversazioni creato in background, per le grandi estrazioni per cui la paginazione è troppo lenta.

Attributi

idstring
Identificatore univoco dell'export.
objectstring
Sempre export.
typestring
Cosa contiene il file, lead oppure conversazioni con i loro messaggi.
leadsconversations
statusstring
processing mentre il file viene creato, poi ready o failed. expired quando il suo link non esiste più.
processingreadyfailedexpired
formatstring
Il formato del file, csv o jsonl per i lead, jsonl o markdown per le conversazioni.
csvjsonlmarkdown
filtersobject
I filtri con cui è stato creato l'export, come in Elenca i lead o Elenca le conversazioni.
row_countinteger
Lead o conversazioni nel file. Il numero cresce mentre il file viene creato. Al massimo 100 000 lead o 20 000 conversazioni.
total_countinteger o null
Per un export di conversazioni senza filtri, quante conversazioni conterrà il file, contate all'inizio della creazione. Altrimenti null.
urlstring o null
Dove scaricare il file, quando è pronto. Funziona per 24 ore, fino a expires_at.
expires_atstring o null
Quando url smette di funzionare, ISO 8601.
created_atstring
Quando è stato creato l'export, ISO 8601.

L'oggetto 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"
}

Crea un export

POST/v1/exportsScope readMCPcreate_export

Inizia a creare un file di lead o di conversazioni. Risponde subito con l'export in processing.

Parametri del body

typestring
Cosa esportare. Di default leads.
leadsconversations
formatstring
Il formato del file. Per i lead csv o jsonl, di default csv. Per le conversazioni jsonl o markdown, di default jsonl.
csvjsonlmarkdown
filtersobject
I lead da esportare, con i filtri di Elenca i lead. Per le conversazioni, solo persona e unread, come in Elenca le conversazioni.

Restituisce

Un oggetto export con lo stato processing, e lo stato HTTP 202.

Errori

400parameter_missing
Manca un parametro obbligatorio. param lo indica.
400parameter_invalid
Un parametro ha un valore che l'API non accetta. param lo indica.
429export_rate_limit_exceeded
Più di 10 export nell'ultima ora sull'account.

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"
    }
  }'

Risposta202

{
  "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"
}

Elenca gli export

GET/v1/exportsScope readMCPlist_exports

Restituisce i tuoi export, dal più recente.

Parametri di query

limitinteger
Quanti oggetti restituire, da 1 a 100. Di default 25.
cursorstring
Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti export.

GET/v1/exports

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

Risposta200

{
  "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
}

Recupera un export

GET/v1/exports/:idScope readMCPget_export

Restituisce un export. Recuperalo ogni qualche secondo finché status è ready, poi scarica url.

Parametri di percorso

idstringObbligatorio
L'ID dell'export.

Restituisce

Un oggetto export.

Errori

404resource_missing
Nessun export con questo ID sull'account della chiave.

GET/v1/exports/:id

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

Risposta200

{
  "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 conversazione nel file

Ogni riga di un file jsonl di conversazioni, dalla conversazione più recente. È l'oggetto conversazione con il suo thread completo, il suo lead e history. Un file markdown contiene le stesse informazioni, con una trascrizione per conversazione.

Attributi

idstring
Identificatore univoco della conversazione.
objectstring
Sempre conversation.
lead_idstring
Il lead con cui stai parlando.
profileobject
Il profilo X del lead, come nell'oggetto lead.
personaobject o null
La buyer persona del lead.
columnobject o null
La colonna della tua board Conversazioni in cui si trova la conversazione.
unreadboolean
True quando l'ultimo messaggio del lead non è ancora stato letto.
messages_countinteger
Messaggi in messages.
first_message_atstring o null
Quando è stato inviato il primo messaggio, ISO 8601.
last_message_atstring o null
Quando è stato inviato l'ultimo messaggio, ISO 8601.
last_messageobject o null
L'ultimo messaggio.
leadobject o null
L'oggetto lead, con punteggio, stato, buyer persona e campagna.
historystring
complete quando messages è il thread completo. recent finché Gemlead conserva solo gli ultimi messaggi di un thread lungo, prima di leggere il resto da X una sola volta.
completerecent
messagesarray di objects
Ogni messaggio del thread, dal più vecchio, con direzione, testo, orario, allegati e reazioni. I link degli allegati funzionano per 24 ore.

Una conversazione nel file

{
  "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
    }
  ]
}