Core concepts

Pagination

Lists come a page at a time. Follow next_cursor until has_more is false and you have every object.

Parameters

Every list endpoint takes the same two parameters, next to its own filters.

limitinteger
How many objects a page holds at most, from 1 to 100. Defaults to 25.
cursorstring
The next_cursor of the page before. Leave it out for the first page.

The list object

objectstring
Always list.
dataarray
The page's objects.
has_moreboolean
True when there is a page after this one.
next_cursorstring or null
The cursor of the next page, null on the last one.

Response200

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

A page can hold fewer objects than limit, even none, while has_more is still true. Each request reads a bounded slice of the index, which keeps filters fast on millions of leads. Always loop on has_more and next_cursor, never on the number of objects.

Keep the same filters and order on every page. A cursor only works with the filters it was made for, otherwise the answer is 400 cursor_invalid.
Cursors are opaque. Never build or change one.
Objects are sorted by the list's order, ties by ID, so a page never repeats an object of the page before.
For tens of thousands of leads, an export is faster than paging.

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

Parameters

The list object

Loop through every page