Gemlead
Docs
Log in
Get your API key

API reference

Sources

Sources decide where Gemlead looks for a persona's leads. A source is an X account whose following or followers are read. A keyword search finds the authors of matching posts. A competitor account brings the people who comment on its posts.

Each one shows the leads it found, scored and hot, so you keep what works. Look up an X profile first to see how good a source it makes.

Endpoints

The source object

An X account whose network Gemlead reads to find a persona's leads. It reads the accounts it follows, its followers, or both.

Attributes

  • idstring
    Unique identifier for the source.
  • objectstring
    Always source.
  • persona_idstring
    The persona it finds leads for.
  • methodstring
    competitor_followers when only its followers are read, else following.
    followingcompetitor_followers
  • profileobject
    The source's X profile.
  • statusstring
    Where reading it stands.
    pendingscrapingscoringdonefailedskipped
  • pausedboolean
    Whether you paused it.
  • errorstring or null
    Why reading it failed, when it did.
  • read_followingboolean
    Whether the accounts it follows are read.
  • read_followersboolean
    Whether its followers are read.
  • score_selfboolean
    Whether the source's own account is scored as a lead too.
  • self_lead_idstring or null
    The lead of the source's own account, once scored.
  • origin_lead_idstring or null
    The lead it came from, when you made it with Turn a lead into a source.
  • statsobject
    What it brought so far.
  • last_activity_atstring or null
    When it last brought a lead, ISO 8601.
  • last_scraped_atstring or null
    When it was last read, ISO 8601.
  • created_atstring
    When it was added, ISO 8601.
Source object
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

List sources

GET/v1/personas/:persona_id/sourcesread scopeMCPlist_sources

Returns the persona's sources with their stats.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Query parameters

  • pausedboolean
    true for paused sources only, false for running ones.
  • 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 source objects.

Errors

GET/v1/personas/:persona_id/sources
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "object": "list",
  "data": [
    {
      "id": "s2HvN8qLtB",
      "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": "done",
      "paused": false,
      "error": null,
      "read_following": true,
      "read_followers": false,
      "score_self": true,
      "self_lead_id": "Lp4WqZ7sXe",
      "origin_lead_id": null,
      "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"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Retrieve a source

GET/v1/personas/:persona_id/sources/:source_idread scopeMCPlist_sources

Returns one source with its stats.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

A source object.

Errors

GET/v1/personas/:persona_id/sources/:source_id
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Add a source

POST/v1/personas/:persona_id/sourceswrite scopeMCPadd_source

Adds an X account as a source. The best are people who look like your buyers, their following is full of peers. A competitor's followers already care about products like yours.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Body parameters

  • usernamestringRequired
    An X username, 1 to 15 letters, digits or _, with or without the @.
  • read_followingboolean
    Read the accounts it follows, the people who look like it. Default true.
  • read_followersboolean
    Read its followers, a competitor's audience for example. Default false.
  • score_selfboolean
    Score the source's own account as a lead too. Default true.

Returns

The new source object.

Errors

POST/v1/personas/:persona_id/sources
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "pickswithmike",
    "read_following": true
  }'
Response200
{
  "id": "s2HvN8qLtB",
  "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": null,
  "stats": {
    "leads": 0,
    "scored_leads": 0,
    "hot_leads": 0,
    "avg_score": 0
  },
  "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"
}

Update a source

PATCH/v1/personas/:persona_id/sources/:source_idwrite scopeMCPupdate_source

Changes what Gemlead reads on the source.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Body parameters

  • read_followingboolean
    Read the accounts it follows, the people who look like it.
  • read_followersboolean
    Read its followers, a competitor's audience for example.
  • score_selfboolean
    Score the source's own account as a lead too.

Returns

The updated source object.

Errors

PATCH/v1/personas/:persona_id/sources/:source_id
curl -X PATCH \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "read_followers": true
  }'
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": true,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Pause a source

POST/v1/personas/:persona_id/sources/:source_id/pausewrite scopeMCPupdate_source

Stops reading the source for now. Its leads stay.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

The source object.

Errors

POST/v1/personas/:persona_id/sources/:source_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": true,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Resume a source

POST/v1/personas/:persona_id/sources/:source_id/resumewrite scopeMCPupdate_source

Starts reading a paused source again.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

The source object.

Errors

POST/v1/personas/:persona_id/sources/:source_id/resume
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/resume \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Skip a source

POST/v1/personas/:persona_id/sources/:source_id/skipwrite scopeMCPupdate_source

Stops a source for good and counts it as done, when it brings the wrong people.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

The source object.

Errors

POST/v1/personas/:persona_id/sources/:source_id/skip
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/skip \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "skipped",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Refresh a source

POST/v1/personas/:persona_id/sources/:source_id/refreshwrite scopeMCPupdate_source

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

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

The source object.

Errors

POST/v1/personas/:persona_id/sources/:source_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Score a source

POST/v1/personas/:persona_id/sources/:source_id/scorewrite scopeMCPupdate_source

Scores the source's own X account as a lead of the persona. Uses up to 2 credits a lead: 1 for the first pass, 1 more for the deep score when it passes.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

The source object.

Errors

POST/v1/personas/:persona_id/sources/:source_id/score
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/score \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "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": "done",
  "paused": false,
  "error": null,
  "read_following": true,
  "read_followers": false,
  "score_self": true,
  "self_lead_id": "Lp4WqZ7sXe",
  "origin_lead_id": null,
  "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"
}

Delete a source

DELETE/v1/personas/:persona_id/sources/:source_idwrite scopeMCPdelete_source

Removes a source and the leads it found that no campaign worked on.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Returns

An object with the source's id, deleted set to true and the count of deleted_leads.

Errors

DELETE/v1/personas/:persona_id/sources/:source_id
curl -X DELETE \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "id": "s2HvN8qLtB",
  "object": "source",
  "deleted": true,
  "deleted_leads": 972
}

List a source's leads

GET/v1/personas/:persona_id/sources/:source_id/leadsread scopeMCPlist_source_leads

Returns the leads a source found, best score first.

Path parameters

  • persona_idstringRequired
    The persona's ID.
  • source_idstringRequired
    The source's ID.

Query parameters

  • orderstring
    -score puts the best leads first, score the lowest. Default -score.
    -scorescore
  • 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, with total_count.

Errors

GET/v1/personas/:persona_id/sources/:source_id/leads
curl -G \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources/s2HvN8qLtB/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -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",
  "total_count": 1184
}

The keyword search object

A search Gemlead runs on X for a persona. The authors of the posts it finds are scored as leads.

Attributes

  • objectstring
    Always search_query.
  • querystring
    The search, as you would type it on X.
  • persona_idstring
    The persona it finds leads for.
  • statsobject
    What it brought so far.
  • first_found_atstring or null
    When it found its first lead, ISO 8601.
Keyword search object
{
  "object": "search_query",
  "query": "paid discord picks",
  "persona_id": "lvWBPnytpS",
  "stats": {
    "leads": 640,
    "scored_leads": 618,
    "hot_leads": 131,
    "avg_score": 47
  },
  "first_found_at": "2026-10-21T10:04:51.000Z"
}

List keyword searches

GET/v1/personas/:persona_id/search_queriesread scopeMCPlist_persona_items

Returns the persona's keyword searches, each with the leads it found, scored and hot.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Returns

A list of keyword search objects.

Errors

GET/v1/personas/:persona_id/search_queries
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "object": "list",
  "data": [
    {
      "object": "search_query",
      "query": "paid discord picks",
      "persona_id": "lvWBPnytpS",
      "stats": {
        "leads": 640,
        "scored_leads": 618,
        "hot_leads": 131,
        "avg_score": 47
      },
      "first_found_at": "2026-10-21T10:04:51.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Add keyword searches

POST/v1/personas/:persona_id/search_querieswrite scopeMCPedit_persona_items

Adds keyword searches to a persona. Gemlead searches X for posts with them and scores their authors.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Body parameters

  • queriesarray of stringsRequired
    1 to 50 keyword searches to add, 500 in all on a persona. Each a search as you would type it on X, 2 to 200 characters.

Returns

The persona's keyword searches, a list of keyword search objects.

Errors

POST/v1/personas/:persona_id/search_queries
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["paid discord picks", "vip tips telegram"]
  }'
Response200
{
  "object": "list",
  "data": [
    {
      "object": "search_query",
      "query": "paid discord picks",
      "persona_id": "lvWBPnytpS",
      "stats": {
        "leads": 640,
        "scored_leads": 618,
        "hot_leads": 131,
        "avg_score": 47
      },
      "first_found_at": "2026-10-21T10:04:51.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Remove keyword searches

POST/v1/personas/:persona_id/search_queries/removewrite scopeMCPedit_persona_items

Removes keyword searches from a persona. The leads they found stay.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Body parameters

  • queriesarray of stringsRequired
    The keyword searches to remove, as listed.

Returns

The persona's keyword searches left, a list of keyword search objects.

Errors

POST/v1/personas/:persona_id/search_queries/remove
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries/remove \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": ["vip tips telegram"]
  }'
Response200
{
  "object": "list",
  "data": [
    {
      "object": "search_query",
      "query": "paid discord picks",
      "persona_id": "lvWBPnytpS",
      "stats": {
        "leads": 640,
        "scored_leads": 618,
        "hot_leads": 131,
        "avg_score": 47
      },
      "first_found_at": "2026-10-21T10:04:51.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

List a keyword search's leads

GET/v1/personas/:persona_id/search_queries/leadsread scopeMCPlist_item_leads

Returns the leads one keyword search found, best score first.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Query parameters

  • querystringRequired
    The keyword search, as listed.
  • orderstring
    -score puts the best leads first, score the lowest. Default -score.
    -scorescore
  • 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, with total_count.

Errors

GET/v1/personas/:persona_id/search_queries/leads
curl -G \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  --data-urlencode "query=paid discord picks" \
  -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",
  "total_count": 640
}

The competitor account object

A competitor's X account. Gemlead reads who comments on its posts and scores them as leads.

Attributes

  • objectstring
    Always competitor_account.
  • usernamestring
    The X username, without the @.
  • persona_idstring
    The persona it finds leads for.
  • statsobject
    What it brought so far.
  • first_found_atstring or null
    When it found its first lead, ISO 8601.
Competitor account object
{
  "object": "competitor_account",
  "username": "whop",
  "persona_id": "lvWBPnytpS",
  "stats": {
    "leads": 905,
    "scored_leads": 902,
    "hot_leads": 96,
    "avg_score": 38
  },
  "first_found_at": "2026-10-24T16:30:12.000Z"
}

List competitor accounts

GET/v1/personas/:persona_id/competitor_accountsread scopeMCPlist_persona_items

Returns the persona's competitor accounts, each with the leads it found, scored and hot.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Returns

A list of competitor account objects.

Errors

GET/v1/personas/:persona_id/competitor_accounts
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "object": "list",
  "data": [
    {
      "object": "competitor_account",
      "username": "whop",
      "persona_id": "lvWBPnytpS",
      "stats": {
        "leads": 905,
        "scored_leads": 902,
        "hot_leads": 96,
        "avg_score": 38
      },
      "first_found_at": "2026-10-24T16:30:12.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Add competitor accounts

POST/v1/personas/:persona_id/competitor_accountswrite scopeMCPedit_persona_items

Adds competitor accounts to a persona. Gemlead reads who comments on their posts and scores them.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Body parameters

  • usernamesarray of stringsRequired
    1 to 50 competitor accounts to add, 100 in all on a persona. Each an X username, with or without the @.

Returns

The persona's competitor accounts, a list of competitor account objects.

Errors

POST/v1/personas/:persona_id/competitor_accounts
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["whop"]
  }'
Response200
{
  "object": "list",
  "data": [
    {
      "object": "competitor_account",
      "username": "whop",
      "persona_id": "lvWBPnytpS",
      "stats": {
        "leads": 905,
        "scored_leads": 902,
        "hot_leads": 96,
        "avg_score": 38
      },
      "first_found_at": "2026-10-24T16:30:12.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Remove competitor accounts

POST/v1/personas/:persona_id/competitor_accounts/removewrite scopeMCPedit_persona_items

Removes competitor accounts from a persona. The leads they found stay.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Body parameters

  • usernamesarray of stringsRequired
    The competitor accounts to remove, as listed.

Returns

The persona's competitor accounts left, a list of competitor account objects.

Errors

POST/v1/personas/:persona_id/competitor_accounts/remove
curl -X POST \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts/remove \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "usernames": ["whop"]
  }'
Response200
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

List a competitor account's leads

GET/v1/personas/:persona_id/competitor_accounts/leadsread scopeMCPlist_item_leads

Returns the leads one competitor account found, best score first.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Query parameters

  • usernamestringRequired
    The competitor's X username, as listed.
  • orderstring
    -score puts the best leads first, score the lowest. Default -score.
    -scorescore
  • 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, with total_count.

Errors

GET/v1/personas/:persona_id/competitor_accounts/leads
curl -G \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d username=whop \
  -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",
  "total_count": 905
}

The source suggestion object

An X account the AI picked as a source for a persona, with why and how to read it.

Attributes

  • objectstring
    Always source_suggestion.
  • profileobject
    Its X profile, as on the X profile object.
  • methodstring
    What to read on it.
    followingcompetitor_followers
  • reasonstring or null
    Why the AI picked it.
  • seed_adviceobject or null
    Gemlead's own check of the account.
Source suggestion object
{
  "object": "source_suggestion",
  "profile": {
    "x_user_id": "1722093311",
    "username": "pickswithmike",
    "name": "Mike Picks",
    "bio": "NBA and NFL picks. VIP Discord, 61 % last season.",
    "followers_count": 8400,
    "following_count": 1210,
    "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
    "verified": false,
    "url": "https://x.com/pickswithmike"
  },
  "method": "following",
  "reason": "Runs a paid picks group and follows dozens of other tipsters.",
  "seed_advice": {
    "verdict": "good",
    "kind": "person",
    "reason_code": "peer",
    "reason": "A founder-sized account (1k to 15k followers) follows peers who look like your buyers.",
    "recommended_method": "following"
  }
}

Suggest sources

GET/v1/personas/:persona_id/source_suggestionsread scopeMCPsuggest_sources

Asks the AI for X accounts to add as sources, picked from the persona's description, keywords and competitors.

Path parameters

  • persona_idstringRequired
    The persona's ID.

Returns

A list of source suggestion objects.

Errors

GET/v1/personas/:persona_id/source_suggestions
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/source_suggestions \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Response200
{
  "object": "list",
  "data": [
    {
      "object": "source_suggestion",
      "profile": {
        "x_user_id": "1722093311",
        "username": "pickswithmike",
        "name": "Mike Picks",
        "bio": "NBA and NFL picks. VIP Discord, 61 % last season.",
        "followers_count": 8400,
        "following_count": 1210,
        "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
        "verified": false,
        "url": "https://x.com/pickswithmike"
      },
      "method": "following",
      "reason": "Runs a paid picks group and follows dozens of other tipsters.",
      "seed_advice": {
        "verdict": "good",
        "kind": "person",
        "reason_code": "peer",
        "reason": "A founder-sized account (1k to 15k followers) follows peers who look like your buyers.",
        "recommended_method": "following"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

The X profile object

An X account read live with your X session, before you add it as a source or a competitor.

Attributes

  • objectstring
    Always x_profile.
  • x_user_idstring
    The X account's numeric ID, as a string.
  • usernamestring
    The X handle, without the @.
  • namestring
    The display name.
  • biostring
    The profile's bio.
  • followers_countinteger
    Followers on X.
  • following_countinteger
    Accounts it follows on X.
  • locationstring
    The location written on the profile.
  • websitestring
    The website on the profile.
  • profile_image_urlstring
    The profile picture's URL.
  • verifiedboolean
    Whether the account has a verified badge.
  • urlstring
    The profile's URL on X.
  • can_dmboolean or null
    Whether your account can DM it, when X says.
  • joined_atstring or null
    When the account was created on X, ISO 8601.
  • seed_adviceobject
    With the persona parameter only. How good a source it makes, once for each way to read it.
X profile object
{
  "object": "x_profile",
  "x_user_id": "1722093311",
  "username": "pickswithmike",
  "name": "Mike Picks",
  "bio": "NBA and NFL picks. VIP Discord, 61 % last season.",
  "followers_count": 8400,
  "following_count": 1210,
  "location": "Las Vegas",
  "website": "https://mikepicks.com",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
  "verified": false,
  "can_dm": true,
  "joined_at": "2019-03-02T18:11:40.000Z",
  "url": "https://x.com/pickswithmike"
}

Look up an X profile

GET/v1/x_profiles/:usernameread scopeMCPlookup_x_profile

Reads an X profile live with your X session. With persona, it also says how good a source the account makes for it.

Path parameters

  • usernamestringRequired
    The X username, with or without the @.

Query parameters

  • personastring
    A persona ID, to get seed_advice for it.

Returns

An X profile object.

Errors

GET/v1/x_profiles/:username
curl -G https://gemlead.ai/api/v1/x_profiles/pickswithmike \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d persona=lvWBPnytpS
Response200
{
  "object": "x_profile",
  "x_user_id": "1722093311",
  "username": "pickswithmike",
  "name": "Mike Picks",
  "bio": "NBA and NFL picks. VIP Discord, 61 % last season.",
  "followers_count": 8400,
  "following_count": 1210,
  "location": "Las Vegas",
  "website": "https://mikepicks.com",
  "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
  "verified": false,
  "can_dm": true,
  "joined_at": "2019-03-02T18:11:40.000Z",
  "url": "https://x.com/pickswithmike",
  "seed_advice": {
    "following": {
      "verdict": "good",
      "kind": "person",
      "reason_code": "peer",
      "reason": "A founder-sized account (1k to 15k followers) follows peers who look like your buyers.",
      "recommended_method": "following"
    },
    "competitor_followers": {
      "verdict": "weak",
      "kind": "person",
      "reason_code": "followers",
      "reason": "Followers lists are mostly passive accounts: few of them score hot. The following of a founder like your buyers works far better.",
      "recommended_method": "following"
    },
    "both": {
      "verdict": "weak",
      "kind": "person",
      "reason_code": "both",
      "reason": "Adding the followers drowns a good following in passive accounts. Keep the following only.",
      "recommended_method": "following"
    }
  }
}
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