API-referentie

Exports

Een export maakt één bestand met alle leads die bij je filters passen, voor hoeveelheden die te groot zijn om te pagineren. Maak de export aan, vraag hem op tot de status ready is en download dan de url. Je kunt per account 10 exports per uur maken.

Met type op conversations bevat het bestand in plaats daarvan alle DM-gesprekken van het account, elk met de lead en alle berichten vanaf het eerste. Het is bedoeld om al je DM's in één keer te bestuderen, met een AI-assistent of je eigen code, en te zien welk openingsbericht antwoorden oplevert en welk antwoord een lead over een bezwaar heen helpt. Gemlead houdt een eigen kopie van al je DM's synchroon met X, bewerkingen en verwijderingen inbegrepen, dus het bestand wordt uit die kopie gebouwd zonder X aan te roepen en 1 500 gesprekken staan in minder dan een minuut klaar.

Endpoints

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

Het exportobject

Een bestand met leads of gesprekken dat op de achtergrond wordt samengesteld, voor grote hoeveelheden waarvoor paginering te traag is.

Attributen

idstring
Unieke ID van de export.
objectstring
Altijd export.
typestring
Wat het bestand bevat, leads of gesprekken met hun berichten.
leadsconversations
statusstring
processing terwijl het bestand wordt samengesteld, daarna ready of failed. expired zodra de link verlopen is.
processingreadyfailedexpired
formatstring
Het formaat van het bestand, csv of jsonl voor leads, jsonl of markdown voor gesprekken.
csvjsonlmarkdown
filtersobject
De filters waarmee de export is gemaakt, zoals in Leads opvragen of Gesprekken opvragen.
row_countinteger
Leads of gesprekken in het bestand. Het aantal groeit terwijl het bestand wordt samengesteld. Maximaal 100 000 leads of 20 000 gesprekken.
total_countinteger of null
Bij een export van gesprekken zonder filters, hoeveel gesprekken het bestand zal bevatten, geteld bij de start van het samenstellen. Anders null.
urlstring of null
Waar je het bestand downloadt, zodra het klaar is. De link werkt 24 uur, tot expires_at.
expires_atstring of null
Wanneer url niet meer werkt, in ISO 8601.
created_atstring
Wanneer de export is gemaakt, in ISO 8601.

Het exportobject

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

Een export maken

POST/v1/exportsScope readMCPcreate_export

Begint met het samenstellen van een bestand met leads of gesprekken. Het antwoord komt meteen, met de export in processing.

Bodyparameters

typestring
Wat je exporteert. Standaard leads.
leadsconversations
formatstring
Het formaat van het bestand. Voor leads csv of jsonl, standaard csv. Voor gesprekken jsonl of markdown, standaard jsonl.
csvjsonlmarkdown
filtersobject
De leads om te exporteren, met de filters van Leads opvragen. Voor gesprekken alleen persona en unread, zoals in Gesprekken opvragen.

Resultaat

Een exportobject met de status processing, en de HTTP-status 202.

Fouten

400parameter_missing
Er ontbreekt een verplichte parameter. param geeft aan welke.
400parameter_invalid
Een parameter heeft een waarde die de API niet accepteert. param geeft aan welke.
429export_rate_limit_exceeded
Meer dan 10 exports in het afgelopen uur op het 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"
    }
  }'

Response202

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

Exports opvragen

GET/v1/exportsScope readMCPlist_exports

Geeft je exports terug, nieuwste eerst.

Queryparameters

limitinteger
Hoeveel objecten je terugkrijgt, van 1 tot 100. Standaard 25.
cursorstring
De next_cursor van de vorige pagina, om de pagina daarna op te halen. Zie Paginering.

Resultaat

Een lijst van exportobjecten.

GET/v1/exports

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

Response200

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

Een export ophalen

GET/v1/exports/:idScope readMCPget_export

Geeft een export terug. Haal hem om de paar seconden op tot status ready is en download dan url.

Padparameters

idstringVerplicht
De ID van de export.

Resultaat

Een exportobject.

Fouten

404resource_missing
Geen export met deze ID op het account van de sleutel.

GET/v1/exports/:id

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

Response200

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

Een gesprek in het bestand

Elke regel van een jsonl-bestand met gesprekken, het nieuwste gesprek eerst. Het is het gespreksobject met de volledige thread, de lead en history. Een markdown-bestand bevat hetzelfde, als één transcript per gesprek.

Attributen

idstring
Unieke ID van het gesprek.
objectstring
Altijd conversation.
lead_idstring
De lead met wie je in gesprek bent.
profileobject
Het X-profiel van de lead, zoals in het lead-object.
personaobject of null
De persona van de lead.
columnobject of null
De kolom van je gesprekkenbord waarin het gesprek staat.
unreadboolean
True als het laatste bericht van de lead nog niet gelezen is.
messages_countinteger
Berichten in messages.
first_message_atstring of null
Wanneer het eerste bericht is verstuurd, in ISO 8601.
last_message_atstring of null
Wanneer het laatste bericht is verstuurd, in ISO 8601.
last_messageobject of null
Het laatste bericht.
leadobject of null
Het lead-object, met de score, status, persona en campagne.
historystring
complete als messages de volledige thread is. recent zolang Gemlead alleen de nieuwste berichten van een lange thread heeft, voordat het de rest één keer van X leest.
completerecent
messagesarray van objects
Alle berichten van de thread, oudste eerst, met richting, tekst, tijd, media en reacties. Medialinks werken 24 uur.

Een gesprek in het bestand

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