API reference

Exports

An export builds one file with every lead that matches your filters, for the pulls too big to page through. Create it, then retrieve it until its status is ready and download its url. You can create 10 exports an hour per account.

With type set to conversations, the file holds every DM conversation of the account instead, each with its lead and every message from the first one. It is made to study your DMs in bulk, with an AI assistant or your own code, to see which opener gets replies and which answer moves a lead past an objection. Gemlead keeps its own copy of every DM in sync with X, edits and deletions included, so the file is built from that copy without a call to X and 1 500 conversations are ready in under a minute.

Endpoints

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

The export object

A file of leads or of conversations built in the background, for the big pulls pagination is too slow for.

Attributes

idstring
Unique identifier for the export.
objectstring
Always export.
typestring
What the file holds, leads or conversations with their messages.
leadsconversations
statusstring
processing while the file is built, then ready or failed. expired once its link is gone.
processingreadyfailedexpired
formatstring
The file's format, csv or jsonl for leads, jsonl or markdown for conversations.
csvjsonlmarkdown
filtersobject
The filters the export was created with, as in List leads or List conversations.
row_countinteger
Leads or conversations in the file. It grows while the file is built. 100 000 leads or 20 000 conversations at most.
total_countinteger or null
For a conversations export without filters, how many conversations the file will hold, counted when the build starts. null otherwise.
urlstring or null
Where to download the file, once ready. It works for 24 hours, until expires_at.
expires_atstring or null
When url stops working, ISO 8601.
created_atstring
When the export was created, ISO 8601.

Export object

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

Create an export

POST/v1/exportsread scopeMCPcreate_export

Starts building a file of leads or of conversations. It answers at once with the export in processing.

Body parameters

typestring
What to export. Defaults to leads.
leadsconversations
formatstring
The file's format. For leads csv or jsonl, csv by default. For conversations jsonl or markdown, jsonl by default.
csvjsonlmarkdown
filtersobject
The leads to export, with the filters of List leads. For conversations, only persona and unread, as in List conversations.

Returns

An export object with the status processing, and the HTTP status 202.

Errors

400parameter_missing
A required parameter is missing. param names it.
400parameter_invalid
A parameter has a value the API does not accept. param names it.
429export_rate_limit_exceeded
More than 10 exports in the last hour on the 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"
}

List exports

GET/v1/exportsread scopeMCPlist_exports

Returns your exports, newest first.

Query parameters

limitinteger
How many objects to return, from 1 to 100. Defaults to 25.
cursorstring
The next_cursor of the previous page, to get the page after it. See Pagination.

Returns

A list of export objects.

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
}

Retrieve an export

GET/v1/exports/:idread scopeMCPget_export

Returns an export. Retrieve it every few seconds until status is ready, then download url.

Path parameters

idstringRequired
The export's ID.

Returns

An export object.

Errors

404resource_missing
No export with this ID on the key's account.

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

A conversation in the file

Each line of a jsonl file of conversations, the latest conversation first. It is the conversation object with its whole thread, its lead and history. A markdown file holds the same, as one transcript per conversation.

Attributes

idstring
Unique identifier for the conversation.
objectstring
Always conversation.
lead_idstring
The lead you are talking to.
profileobject
The lead's X profile, as on the lead object.
personaobject or null
The lead's persona.
columnobject or null
The column of your Conversations board the conversation sits in.
unreadboolean
True when the lead's last message is not read yet.
messages_countinteger
Messages in messages.
first_message_atstring or null
When the first message was sent, ISO 8601.
last_message_atstring or null
When the last message was sent, ISO 8601.
last_messageobject or null
The last message.
leadobject or null
The lead object, with its score, status, persona and campaign.
historystring
complete when messages is the whole thread. recent while Gemlead holds only the latest messages of a long thread, before it reads the rest from X once.
completerecent
messagesarray of objects
Every message of the thread, oldest first, with its direction, text, time, media and reactions. Media links work for 24 hours.

A conversation in the 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
    }
  ]
}