Concepts clés

Pagination

Les listes arrivent page par page. Suis next_cursor jusqu'à ce que has_more vaille false pour avoir tous les objets.

Paramètres

Chaque endpoint de liste prend les deux mêmes paramètres, en plus de ses propres filtres.

limitinteger
Le nombre maximum d'objets par page, de 1 à 100. 25 par défaut.
cursorstring
Le next_cursor de la page précédente. Ne l'envoie pas pour la première page.

L'objet liste

objectstring
Toujours list.
dataarray
Les objets de la page.
has_moreboolean
Vaut true s'il y a une page après celle-ci.
next_cursorstring ou null
Le curseur de la page suivante, null sur la dernière.

Réponse200

{
  "object": "list",
  "data": [
    {
      "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": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

Une page peut contenir moins d'objets que limit, voire aucun, alors que has_more vaut encore true. Chaque requête lit une tranche limitée de l'index, ce qui permet aux filtres de rester rapides sur des millions de leads. Boucle toujours sur has_more et next_cursor, jamais sur le nombre d'objets.

Garde les mêmes filtres et le même order sur chaque page. Un curseur ne marche qu'avec les filtres pour lesquels il a été créé, sinon la réponse est 400 cursor_invalid.
Les curseurs sont opaques. Ne les construis ni ne les modifie jamais.
Les objets sont triés selon l'ordre de la liste, puis par ID en cas d'égalité, donc une page ne répète jamais un objet de la page précédente.
Pour des dizaines de milliers de leads, un export est plus rapide que la pagination.

curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=100

# The next page, with the next_cursor of the one before
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=100 \
  -d cursor=eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0

Paramètres

L'objet liste

Parcourir toutes les pages