Gemlead
Docs
Log in
Get your API key

API reference

Leads

Leads are the people Gemlead finds on X for your personas. Dana AI scores each one from 0 to 100, and a lead is hot at 60 or more. List them with filters, attach your own metadata like a CRM ID, or act on one as you would in the app.

Endpoints

The lead object

A person Gemlead found on X for one of your personas, with the score Dana AI gave them and where they are in your outreach.

Attributes

  • idstring
    Unique identifier for the lead.
  • objectstring
    Always lead.
  • profileobject
    The lead's X profile.
  • scoreinteger or null
    How well the lead fits your persona, from 0 to 100. Null until scored.
  • score_reasonstring or null
    Why the lead got this score, in one or two sentences.
  • hotboolean
    True when the score is 60 or more.
  • statusstring
    Where the lead is in your pipeline.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • personaobject or null
    The persona the lead was found for.
  • campaignobject or null
    The campaign the lead is in, if any.
  • conversation_idstring or null
    The conversation with the lead once one exists. Use it with Retrieve a conversation.
  • locked_toobject or null
    The one X account of the owner this person is kept for. A lead goes to one X account only, so the others never contact them. Null when nothing holds the lead yet.
  • found_atstring
    When Gemlead found the lead, ISO 8601.
  • scored_atstring or null
    When the lead was scored, ISO 8601.
  • updated_atstring
    When the lead last changed, ISO 8601.
  • metadataobject
    Your own key value pairs, set with Update a lead.
Lead object
{
  "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": {}
}

List leads

GET/v1/leadsread scopeMCPsearch_leads

Returns your leads, newest scored first by default. Combine filters to get exactly the leads you want.

Query parameters

  • personastring
    Only leads of this persona ID.
  • statusstring
    Only leads in these statuses, comma separated, like scored,in_campaign.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • score_mininteger
    Only leads with at least this score, from 0 to 100.
  • score_maxinteger
    Only leads with at most this score, from 0 to 100.
  • hotboolean
    true for leads that scored 60 or more, false for the others.
  • scored_afterstring
    Only leads scored after this time, ISO 8601.
  • scored_beforestring
    Only leads scored before this time, ISO 8601.
  • found_afterstring
    Only leads found after this time, ISO 8601.
  • found_beforestring
    Only leads found before this time, ISO 8601.
  • orderstring
    The sort order. Defaults to -scored_at, the most recently scored first.
    -scored_at-score-found_at
  • limitinteger
    How many objects to return, from 1 to 100. Defaults to 25.
  • cursorstring
    The next_cursor of the previous page, to get the page after it. See Pagination.

Returns

A list of lead objects.

Errors

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

Retrieve a lead

GET/v1/leads/:idread scopeMCPget_lead

Returns one lead.

Path parameters

  • idstringRequired
    The lead's ID.

Returns

A lead object.

Errors

GET/v1/leads/:id
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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": {}
}

Update a lead

PATCH/v1/leads/:idwrite scopeMCPupdate_lead

Sets your own metadata on a lead, or closes it when you are done with it. Closing a lead stops the campaign steps still waiting for it, so Gemlead stops writing to it.

Path parameters

  • idstringRequired
    The lead's ID.

Body parameters

  • metadataobject
    Key value pairs merged into the lead's metadata. Keys up to 40 letters, digits, _ or -, values strings up to 500 characters, 20 keys at most. Set a key to null or an empty string to remove it, or metadata to null to clear them all.
  • statusstring
    Set to closed to close the lead.
    closed

Returns

The updated lead object.

Errors

PATCH/v1/leads/:id
curl -X PATCH https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_id": "hs_48213"
    }
  }'
Response200
{
  "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": {
    "crm_id": "hs_48213"
  }
}

Rescore a lead

POST/v1/leads/:lead_id/rescorewrite scopeMCPlead_action

Asks Dana AI to score the lead again against its persona, after you changed the persona's description for example. Uses up to 2 credits a lead: 1 for the first pass, 1 more for the deep score when it passes.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

The lead object.

Errors

POST/v1/leads/:lead_id/rescore
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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": {}
}

Refresh a lead

POST/v1/leads/:lead_id/refreshwrite scopeMCPlead_action

Reads the lead's X profile again, for a new bio, photo or follower count.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

The updated lead object.

Errors

POST/v1/leads/:lead_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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": {}
}

Follow a lead

POST/v1/leads/:lead_id/followwrite scopeMCPlead_action

Follows the lead on X from your X account, right away.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

The lead object.

Errors

POST/v1/leads/:lead_id/follow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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": {}
}

Unfollow a lead

POST/v1/leads/:lead_id/unfollowwrite scopeMCPlead_action

Unfollows the lead on X from your X account, right away.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

The lead object.

Errors

POST/v1/leads/:lead_id/unfollow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "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": {}
}

Turn a lead into a source

POST/v1/leads/:lead_id/convert_to_sourcewrite scopeMCPconvert_lead_to_source

Makes a great lead a source of its persona, to find more people like it. Gemlead reads who it follows, its followers, or who comments on its posts.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Body parameters

  • methodstring
    following reads who the lead follows, competitor_followers its followers, competitor_comments who comments on its posts. Default following.
    followingcompetitor_followerscompetitor_comments

Returns

An object with the lead_id, its persona_id, the method, and the new source, or the competitor_account username for competitor_comments.

Errors

POST/v1/leads/:lead_id/convert_to_source
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/convert_to_source \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "following"
  }'
Response200
{
  "object": "lead_conversion",
  "lead_id": "msgOtJ8dvT",
  "persona_id": "lvWBPnytpS",
  "method": "following",
  "source": {
    "id": "s9KdT3pXwM",
    "object": "source",
    "persona_id": "lvWBPnytpS",
    "method": "following",
    "profile": {
      "username": "pickswithmike",
      "name": "Mike Picks",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
      "followers_count": 8400,
      "following_count": 1210,
      "url": "https://x.com/pickswithmike"
    },
    "status": "pending",
    "paused": false,
    "error": null,
    "read_following": true,
    "read_followers": false,
    "score_self": true,
    "self_lead_id": "Lp4WqZ7sXe",
    "origin_lead_id": "msgOtJ8dvT",
    "stats": {
      "leads": 1184,
      "scored_leads": 1160,
      "hot_leads": 212,
      "avg_score": 44
    },
    "last_activity_at": "2026-11-05T14:03:40.117Z",
    "last_scraped_at": "2026-11-05T14:02:11.482Z",
    "created_at": "2026-09-14T09:21:05.300Z"
  },
  "competitor_account": null
}

Delete a lead

DELETE/v1/leads/:lead_idwrite scopeMCPdelete_lead

Deletes a lead. It leaves your lists and every campaign stops for it, and Gemlead does not bring the same person back for this persona. To keep someone out of every persona, add them to the exclusion list.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

An object with the lead's id and deleted set to true.

Errors

DELETE/v1/leads/:lead_id
curl -X DELETE https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "deleted": true
}

The lead origin object

How Gemlead found a lead, the post that surfaced it, and every campaign it is in.

Attributes

  • objectstring
    Always lead_origin.
  • lead_idstring
    The lead's ID.
  • personaobject or null
    The persona it was found for.
  • methodstring or null
    How it was found.
    followingkeywordscompetitor_followerscompetitor_comments
  • found_querystring or null
    The keyword search that found it, for keywords.
  • source_usernamestring or null
    The source or competitor account it was found through.
  • found_postobject or null
    The post that surfaced the lead, when a post did.
  • campaignsarray of objects
    The campaigns the lead is in, each with its id, name, the lead's status in it, the campaign's method and the step the lead is on.
Lead origin object
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}

Retrieve a lead's origin

GET/v1/leads/:lead_id/originread scopeMCPget_lead_origin

Returns how Gemlead found the lead, the post that surfaced it and every campaign it is in, with the step it is on.

Path parameters

  • lead_idstringRequired
    The lead's ID.

Returns

A lead origin object.

Errors

GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}
Get Gemlead updates
delivered directly to your inbox.
Subscribe
By subscribing you agree to our Privacy Policy and provide consent to receive updates from our company.
Gemlead
Product
Get started
Log in
Who it's for
AI agents
Features
Pricing
Affiliate
FAQ
Features
Buyers found 24/7Hot leads first60%+ reply rateMind-reading DMsEvery DM, one inboxYour AI closerScale without limitsAPI, MCP, webhooksJust ask Gemlead
Resources
HomeAPIBlog
Legal
Terms
Privacy
© 2026 Gemlead, Inc. All rights reserved.
English