API-Referenz

Exporte

Ein Export erstellt eine Datei mit allen Leads, die zu deinen Filtern passen, für Abfragen, die zu groß zum Durchblättern sind. Erstelle ihn, rufe ihn ab, bis sein status gleich ready ist, und lade seine url herunter. Pro Konto kannst du 10 Exporte pro Stunde erstellen.

Ist type auf conversations gesetzt, enthält die Datei stattdessen alle DM-Unterhaltungen des Kontos, jede mit ihrem Lead und allen Nachrichten ab der ersten. Sie ist dafür gemacht, deine DMs im großen Stil auszuwerten, mit einem KI-Assistenten oder deinem eigenen Code, um zu sehen, welche Eröffnungsnachricht Antworten bekommt und welche Antwort einen Einwand des Leads ausräumt. Gemlead hält eine eigene Kopie aller DMs mit X synchron, Bearbeitungen und Löschungen eingeschlossen, deshalb entsteht die Datei aus dieser Kopie ohne Aufruf an X und 1 500 Unterhaltungen sind in weniger als einer Minute fertig.

Endpoints

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

Das Exportobjekt

Eine Datei mit Leads oder Unterhaltungen, im Hintergrund erstellt, für große Abfragen, bei denen Paginierung zu langsam ist.

Attribute

idstring
Eindeutige Kennung des Exports.
objectstring
Immer export.
typestring
Was die Datei enthält, Leads oder Unterhaltungen mit ihren Nachrichten.
leadsconversations
statusstring
processing, solange die Datei erstellt wird, dann ready oder failed. expired, sobald ihr Link abgelaufen ist.
processingreadyfailedexpired
formatstring
Das Format der Datei, csv oder jsonl für Leads, jsonl oder markdown für Unterhaltungen.
csvjsonlmarkdown
filtersobject
Die Filter, mit denen der Export erstellt wurde, wie bei Leads auflisten oder Unterhaltungen auflisten.
row_countinteger
Leads oder Unterhaltungen in der Datei. Die Zahl wächst, während die Datei erstellt wird. Höchstens 100 000 Leads oder 20 000 Unterhaltungen.
total_countinteger oder null
Bei einem Export von Unterhaltungen ohne Filter, wie viele Unterhaltungen die Datei enthalten wird, gezählt beim Start der Erstellung. Sonst null.
urlstring oder null
Wo die Datei heruntergeladen werden kann, sobald sie fertig ist. Der Link funktioniert 24 Stunden lang, bis expires_at.
expires_atstring oder null
Wann url nicht mehr funktioniert, ISO 8601.
created_atstring
Wann der Export erstellt wurde, ISO 8601.

Das Exportobjekt

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

Export erstellen

POST/v1/exportsScope readMCPcreate_export

Beginnt mit dem Erstellen einer Datei mit Leads oder Unterhaltungen. Antwortet sofort mit dem Export im Status processing.

Body-Parameter

typestring
Was exportiert wird. Standardmäßig leads.
leadsconversations
formatstring
Das Format der Datei. Für Leads csv oder jsonl, standardmäßig csv. Für Unterhaltungen jsonl oder markdown, standardmäßig jsonl.
csvjsonlmarkdown
filtersobject
Die zu exportierenden Leads, mit den Filtern von Leads auflisten. Für Unterhaltungen nur persona und unread, wie bei Unterhaltungen auflisten.

Rückgabe

Ein Exportobjekt mit dem Status processing und dem HTTP-Status 202.

Fehler

400parameter_missing
Ein Pflichtparameter fehlt. param nennt ihn.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.
429export_rate_limit_exceeded
Mehr als 10 Exporte in der letzten Stunde in diesem Konto.

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

Antwort202

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

Exporte auflisten

GET/v1/exportsScope readMCPlist_exports

Gibt deine Exporte zurück, die neuesten zuerst.

Query-Parameter

limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Exportobjekten.

GET/v1/exports

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

Antwort200

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

Export abrufen

GET/v1/exports/:idScope readMCPget_export

Gibt einen Export zurück. Rufe ihn alle paar Sekunden ab, bis status gleich ready ist, und lade dann url herunter.

Pfadparameter

idstringErforderlich
Die ID des Exports.

Rückgabe

Ein Exportobjekt.

Fehler

404resource_missing
Kein Export mit dieser ID im Konto des Schlüssels.

GET/v1/exports/:id

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

Antwort200

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

Eine Unterhaltung in der Datei

Jede Zeile einer jsonl-Datei mit Unterhaltungen, die neueste Unterhaltung zuerst. Sie enthält das Unterhaltungsobjekt mit dem ganzen Verlauf, dem Lead und history. Eine markdown-Datei enthält dasselbe, als ein Transkript pro Unterhaltung.

Attribute

idstring
Eindeutige Kennung der Unterhaltung.
objectstring
Immer conversation.
lead_idstring
Der Lead, mit dem du schreibst.
profileobject
Das X-Profil des Leads, wie im Lead-Objekt.
personaobject oder null
Die Persona des Leads.
columnobject oder null
Die Spalte im Board deiner Unterhaltungen, in der die Unterhaltung liegt.
unreadboolean
True, wenn die letzte Nachricht des Leads noch nicht gelesen ist.
messages_countinteger
Nachrichten in messages.
first_message_atstring oder null
Wann die erste Nachricht gesendet wurde, ISO 8601.
last_message_atstring oder null
Wann die letzte Nachricht gesendet wurde, ISO 8601.
last_messageobject oder null
Die letzte Nachricht.
leadobject oder null
Das Lead-Objekt, mit Score, Status, Persona und Kampagne.
historystring
complete, wenn messages der ganze Verlauf ist. recent, solange Gemlead nur die neuesten Nachrichten eines langen Verlaufs hat, bevor es den Rest einmal von X liest.
completerecent
messagesArray von objects
Jede Nachricht des Verlaufs, die älteste zuerst, mit Richtung, Text, Zeitpunkt, Anhängen und Reaktionen. Links zu Anhängen funktionieren 24 Stunden lang.

Eine Unterhaltung in der Datei

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