Référence API

Exports

Un export crée un seul fichier avec tous les leads qui correspondent à tes filtres, pour les extractions trop volumineuses pour être paginées. Crée-le, puis récupère-le jusqu'à ce que son status soit ready, et télécharge son url. Tu peux créer 10 exports par heure et par compte.

Avec type à conversations, le fichier contient à la place toutes les conversations en DM du compte, chacune avec son lead et tous ses messages depuis le premier. Il sert à étudier tes DM en masse, avec un assistant IA ou ton propre code, pour voir quelle accroche obtient des réponses et quelle réponse lève les objections d'un lead. Gemlead garde sa propre copie de tous tes DM, synchronisée avec X, modifications et suppressions comprises, donc le fichier est construit depuis cette copie sans appel à X et 1 500 conversations sont prêtes en moins d'une minute.

Endpoints

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

L'objet export

Un fichier de leads ou de conversations créé en arrière-plan, pour les grosses extractions où la pagination est trop lente.

Attributs

idstring
Identifiant unique de l'export.
objectstring
Toujours export.
typestring
Ce que contient le fichier, des leads ou des conversations avec leurs messages.
leadsconversations
statusstring
processing pendant la création du fichier, puis ready ou failed. expired une fois son lien expiré.
processingreadyfailedexpired
formatstring
Le format du fichier, csv ou jsonl pour les leads, jsonl ou markdown pour les conversations.
csvjsonlmarkdown
filtersobject
Les filtres avec lesquels l'export a été créé, comme dans Lister les leads ou Lister les conversations.
row_countinteger
Les leads ou les conversations du fichier. Ce nombre augmente pendant la création du fichier. 100 000 leads ou 20 000 conversations au plus.
total_countinteger ou null
Pour un export de conversations sans filtre, le nombre de conversations que contiendra le fichier, compté au début de sa création. null sinon.
urlstring ou null
Où télécharger le fichier, une fois prêt. Le lien reste valable 24 heures, jusqu'à expires_at.
expires_atstring ou null
Date d'expiration de url, en ISO 8601.
created_atstring
Date de création de l'export, en ISO 8601.

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

Créer un export

POST/v1/exportsScope readMCPcreate_export

Lance la création d'un fichier de leads ou de conversations. La réponse arrive aussitôt, avec l'export en processing.

Paramètres du corps

typestring
Ce qu'il faut exporter. leads par défaut.
leadsconversations
formatstring
Le format du fichier. Pour les leads, csv ou jsonl, csv par défaut. Pour les conversations, jsonl ou markdown, jsonl par défaut.
csvjsonlmarkdown
filtersobject
Les leads à exporter, avec les filtres de Lister les leads. Pour les conversations, seulement persona et unread, comme dans Lister les conversations.

Renvoie

Un objet export avec le statut processing, et le statut HTTP 202.

Erreurs

400parameter_missing
Il manque un paramètre obligatoire. param indique lequel.
400parameter_invalid
Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
429export_rate_limit_exceeded
Plus de 10 exports dans la dernière heure sur le compte.

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

Réponse202

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

Lister les exports

GET/v1/exportsScope readMCPlist_exports

Renvoie tes exports, les plus récents en premier.

Paramètres de requête

limitinteger
Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
cursorstring
Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets export.

GET/v1/exports

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

Réponse200

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

Récupérer un export

GET/v1/exports/:idScope readMCPget_export

Renvoie un export. Récupère-le à intervalles de quelques secondes jusqu'à ce que status soit ready, puis télécharge url.

Paramètres de chemin

idstringObligatoire
L'ID de l'export.

Renvoie

Un objet export.

Erreurs

404resource_missing
Aucun export avec cet ID sur le compte de la clé.

GET/v1/exports/:id

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

Réponse200

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

Une conversation du fichier

Chaque ligne d'un fichier jsonl de conversations, la conversation la plus récente en premier. C'est l'objet conversation avec son fil complet, son lead et le champ history. Un fichier markdown contient la même chose, sous forme d'une transcription par conversation.

Attributs

idstring
Identifiant unique de la conversation.
objectstring
Toujours conversation.
lead_idstring
Le lead avec qui tu échanges.
profileobject
Le profil X du lead, comme dans l'objet lead.
personaobject ou null
Le persona du lead.
columnobject ou null
La colonne du tableau des conversations où elle se trouve.
unreadboolean
Vaut true quand le dernier message du lead n'est pas encore lu.
messages_countinteger
Messages dans messages.
first_message_atstring ou null
Date du premier message, en ISO 8601.
last_message_atstring ou null
Date du dernier message, en ISO 8601.
last_messageobject ou null
Le dernier message.
leadobject ou null
L'objet lead, avec son score, son statut, son persona et sa campagne.
historystring
complete quand messages contient tout le fil. recent tant que Gemlead ne garde que les derniers messages d'un long fil, avant de lire le reste sur X une seule fois.
completerecent
messagestableau d'objects
Tous les messages du fil, du plus ancien au plus récent, avec leur sens d'envoi, leur texte, leur date, leurs pièces jointes et leurs réactions. Les liens des pièces jointes restent valables 24 heures.

Une conversation du fichier

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