基本概念

ページネーション

一覧は1ページずつ返ります。has_moreがfalseになるまでnext_cursorをたどれば、すべてのオブジェクトを取得できます。

パラメーター

一覧のエンドポイントはすべて、それぞれのフィルターに加えて、次の2つの共通パラメーターを受け付けます。

limitinteger
1ページに含まれるオブジェクトの最大数。1から100まで指定でき、デフォルトは25です。
cursorstring
前のページのnext_cursor。最初のページでは省略します。

リストオブジェクト

objectstring
常にlistです。
dataarray
このページのオブジェクト。
has_moreboolean
次のページがある場合はtrue。
next_cursorstringまたはnull
次のページのカーソル。最後のページではnullです。

レスポンス200

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

すべてのページを取得する

has_moreがtrueでも、ページ内のオブジェクトがlimitより少ないことや、0件のこともあります。各リクエストはインデックスの一定範囲だけを読むため、数百万件のリードでもフィルターが速く動きます。ループは必ずhas_moreとnext_cursorで判定し、オブジェクトの件数では判定しないでください。

すべてのページで同じフィルターとorderを使ってください。カーソルは発行時と同じフィルターでのみ有効で、異なる場合は400 cursor_invalidが返ります。
カーソルは不透明な値です。自分で組み立てたり、変更したりしないでください。
オブジェクトは一覧の並び順で、同じ値の場合はID順に並ぶため、前のページと同じオブジェクトが繰り返されることはありません。
数万件のリードを取得するなら、ページ送りよりエクスポートのほうが速く済みます。

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