Getting started

Gemlead API

Bring the hot leads Gemlead finds on X into your own tools. A REST API, signed webhooks and an MCP server for AI assistants, all on one key.

Before you start

The API and the MCP server come with the Business and Enterprise plans, trial included. Every endpoint lives under https://gemlead.ai/api/v1, takes and returns JSON with snake_case fields, and writes every date and time in ISO 8601, in UTC.

Base URL

https://gemlead.ai/api/v1

Get an API key

In Gemlead, open API in the menu. Pick the X account the key is for, name it and choose its scopes, read alone or read and write.

The key starts with gl_live_ and shows once, so put it right away in your secret manager or in your environment. A key belongs to one X account and only ever sees its data.

Terminal

export GEMLEAD_API_KEY="gl_live_..."

Make your first request

Check the key with Retrieve the account. Every request sends the key in the Authorization header, as a bearer token.

The answer is the X account the key belongs to, and its plan.

GET/v1/account

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

Response200

{
  "object": "account",
  "id": "a9PzK2vRtM",
  "username": "acme",
  "name": "Acme",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1180044592/acme_400x400.jpg",
  "plan": "business"
}

List your hot leads

A lead is hot when Dana AI scores it 60 or more. Ask for the latest ones with hot=true, and add persona, score_min or a date to narrow the list down.

Lists come a page at a time. Follow next_cursor while has_more is true, as Pagination shows.

GET/v1/leads

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

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

Receive your first webhook

Webhooks push events to your server the moment they happen, so you never poll. Register a public HTTPS URL for lead.hot and reply.received, keep the secret of the response, then send yourself a test event. lead.created sends every new lead, hot or not.

Check every request with its Gemlead-Signature header, as Verify signatures shows. You can also add the endpoint in the app, under API.

POST/v1/webhook_endpoints

curl -X POST https://gemlead.ai/api/v1/webhook_endpoints \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/gemlead",
    "events": ["lead.hot", "reply.received"],
    "description": "CRM sync",
    "filters": {
      "persona_ids": ["lvWBPnytpS"]
    }
  }'

POST/v1/webhook_endpoints/:id/test

curl -X POST \
  https://gemlead.ai/api/v1/webhook_endpoints/wh3LpX9dKe/test \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Connect an AI assistant

Gemlead's MCP server at https://gemlead.ai/mcp lets Claude, ChatGPT and Cursor search your leads, read your conversations and run your campaigns, right in the chat.

In Claude Code, one command connects it with your key. For the others, follow MCP setup.

Claude Code

claude mcp add --transport http gemlead https://gemlead.ai/mcp \
  --header "Authorization: Bearer $GEMLEAD_API_KEY"

Next steps

AuthenticationKeys, scopes and how to keep them safe.LeadsEvery filter of the leads list, and the lead object.WebhooksEvents, payloads, signatures and retries.MCP serverSet up Claude, ChatGPT, Cursor and Claude Code.