Gemlead
Docs
Entrar
Obter sua chave de API

Referência da API

Fontes

As fontes definem onde o Gemlead procura os leads de uma persona. Uma fonte é uma conta do X da qual o Gemlead lê quem ela segue ou os seguidores dela. Uma busca por palavra-chave encontra os autores dos posts que correspondem a ela. Uma conta concorrente traz as pessoas que comentam nos posts dela.

Cada uma mostra quantos leads encontrou, quantos foram pontuados e quantos estão quentes, para você manter o que funciona. Consulte um perfil do X antes para ver o quanto ele vale como fonte.

Endpoints

O objeto source

Uma conta do X cuja rede o Gemlead lê para encontrar os leads de uma persona. Ele lê as contas que ela segue, os seguidores dela ou os dois.

Atributos

  • idstring
    Identificador único da fonte.
  • objectstring
    Sempre source.
  • persona_idstring
    A persona para a qual ela encontra leads.
  • methodstring
    competitor_followers quando só os seguidores dela são lidos, senão following.
    followingcompetitor_followers
  • profileobject
    O perfil da fonte no X.
  • statusstring
    Em que ponto está a leitura dela.
    pendingscrapingscoringdonefailedskipped
  • pausedboolean
    Indica se você pausou a fonte.
  • errorstring ou null
    Por que a leitura falhou, quando falhou.
  • read_followingboolean
    Indica se as contas que ela segue são lidas.
  • read_followersboolean
    Indica se os seguidores dela são lidos.
  • score_selfboolean
    Indica se a própria conta da fonte também é pontuada como lead.
  • self_lead_idstring ou null
    O lead da própria conta da fonte, depois de pontuado.
  • origin_lead_idstring ou null
    O lead de origem, quando você a criou com Transformar um lead em fonte.
  • statsobject
    O que ela trouxe até agora.
  • last_activity_atstring ou null
    Quando ela trouxe um lead pela última vez, em ISO 8601.
  • last_scraped_atstring ou null
    Quando ela foi lida pela última vez, em ISO 8601.
  • created_atstring
    Quando ela foi adicionada, em ISO 8601.
O objeto source
{
  "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"
}

Listar fontes

GET/v1/personas/:persona_id/sourcesScope readMCPlist_sources

Retorna as fontes da persona com as estatísticas delas.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros de consulta

  • pausedboolean
    true só para as fontes pausadas, false para as ativas.
  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos source.

Erros

GET/v1/personas/:persona_id/sources
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "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
}

Obter uma fonte

GET/v1/personas/:persona_id/sources/:source_idScope readMCPlist_sources

Retorna uma fonte com as estatísticas dela.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

Um objeto source.

Erros

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

Adicionar uma fonte

POST/v1/personas/:persona_id/sourcesScope writeMCPadd_source

Adiciona uma conta do X como fonte. As melhores são pessoas parecidas com os seus compradores, porque elas seguem muita gente do mesmo perfil. Os seguidores de um concorrente já se interessam por produtos como o seu.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • usernamestringObrigatório
    Um username do X, de 1 a 15 letras, dígitos ou _, com ou sem o @.
  • read_followingboolean
    Lê as contas que ela segue, pessoas parecidas com ela. O padrão é true.
  • read_followersboolean
    Lê os seguidores dela, o público de um concorrente, por exemplo. O padrão é false.
  • score_selfboolean
    Pontua também a própria conta da fonte como lead. O padrão é true.

Retorno

O novo objeto source.

Erros

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

Atualizar uma fonte

PATCH/v1/personas/:persona_id/sources/:source_idScope writeMCPupdate_source

Altera o que o Gemlead lê na fonte.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Parâmetros do corpo

  • read_followingboolean
    Lê as contas que ela segue, pessoas parecidas com ela.
  • read_followersboolean
    Lê os seguidores dela, o público de um concorrente, por exemplo.
  • score_selfboolean
    Pontua também a própria conta da fonte como lead.

Retorno

O objeto source atualizado.

Erros

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

Pausar uma fonte

POST/v1/personas/:persona_id/sources/:source_id/pauseScope writeMCPupdate_source

Para de ler a fonte por enquanto. Os leads dela continuam lá.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

O objeto source.

Erros

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

Retomar uma fonte

POST/v1/personas/:persona_id/sources/:source_id/resumeScope writeMCPupdate_source

Volta a ler uma fonte pausada.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

O objeto source.

Erros

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

Pular uma fonte

POST/v1/personas/:persona_id/sources/:source_id/skipScope writeMCPupdate_source

Encerra uma fonte de vez e a marca como concluída, quando ela traz as pessoas erradas.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

O objeto source.

Erros

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

Recarregar uma fonte

POST/v1/personas/:persona_id/sources/:source_id/refreshScope writeMCPupdate_source

Lê de novo o perfil da fonte no X, para obter um novo nome, foto ou número de seguidores.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

O objeto source.

Erros

  • 404resource_missing
    Nenhuma fonte com este ID na conta da chave.
  • 409x_session_expired
    A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.
  • 502upstream_unavailable
    O X ou um serviço do Gemlead não respondeu. Nada mudou, tente de novo em um minuto.
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"
Resposta200
{
  "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"
}

Pontuar uma fonte

POST/v1/personas/:persona_id/sources/:source_id/scoreScope writeMCPupdate_source

Pontua a própria conta do X da fonte como lead da persona. Usa até 2 créditos por lead: 1 pela primeira triagem, mais 1 pelo score aprofundado quando o lead passa.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

O objeto source.

Erros

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

Excluir uma fonte

DELETE/v1/personas/:persona_id/sources/:source_idScope writeMCPdelete_source

Remove uma fonte e os leads que ela encontrou e que nenhuma campanha trabalhou.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Retorno

Um objeto com o id da fonte, deleted igual a true e a contagem de deleted_leads.

Erros

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"
Resposta200
{
  "id": "s2HvN8qLtB",
  "object": "source",
  "deleted": true,
  "deleted_leads": 972
}

Listar os leads de uma fonte

GET/v1/personas/:persona_id/sources/:source_id/leadsScope readMCPlist_source_leads

Retorna os leads que uma fonte encontrou, do maior score para o menor.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.
  • source_idstringObrigatório
    O ID da fonte.

Parâmetros de consulta

  • orderstring
    -score coloca os melhores leads primeiro, score os mais baixos. O padrão é -score.
    -scorescore
  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos lead, com total_count.

Erros

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

O objeto keyword search

Uma busca que o Gemlead faz no X para uma persona. Os autores dos posts que ela encontra são pontuados como leads.

Atributos

  • objectstring
    Sempre search_query.
  • querystring
    A busca, como você a digitaria no X.
  • persona_idstring
    A persona para a qual ela encontra leads.
  • statsobject
    O que ela trouxe até agora.
  • first_found_atstring ou null
    Quando ela encontrou o primeiro lead, em ISO 8601.
O objeto keyword search
{
  "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"
}

Listar buscas por palavra-chave

GET/v1/personas/:persona_id/search_queriesScope readMCPlist_persona_items

Retorna as buscas por palavra-chave da persona, cada uma com os leads encontrados, pontuados e quentes.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Retorno

Uma lista de objetos keyword search.

Erros

GET/v1/personas/:persona_id/search_queries
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "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
}

Adicionar buscas por palavra-chave

POST/v1/personas/:persona_id/search_queriesScope writeMCPedit_persona_items

Adiciona buscas por palavra-chave a uma persona. O Gemlead procura no X posts com esses termos e pontua os autores.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • queriesarray de stringsObrigatório
    De 1 a 50 buscas por palavra-chave a adicionar, 500 no total numa persona. Cada uma é uma busca como você a digitaria no X, de 2 a 200 caracteres.

Retorno

As buscas por palavra-chave da persona, uma lista de objetos keyword search.

Erros

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"]
  }'
Resposta200
{
  "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
}

Remover buscas por palavra-chave

POST/v1/personas/:persona_id/search_queries/removeScope writeMCPedit_persona_items

Remove buscas por palavra-chave de uma persona. Os leads que elas encontraram continuam lá.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • queriesarray de stringsObrigatório
    As buscas por palavra-chave a remover, como aparecem na lista.

Retorno

As buscas por palavra-chave que restam na persona, uma lista de objetos keyword search.

Erros

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"]
  }'
Resposta200
{
  "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
}

Listar os leads de uma busca por palavra-chave

GET/v1/personas/:persona_id/search_queries/leadsScope readMCPlist_item_leads

Retorna os leads que uma busca por palavra-chave encontrou, do maior score para o menor.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros de consulta

  • querystringObrigatório
    A busca por palavra-chave, como aparece na lista.
  • orderstring
    -score coloca os melhores leads primeiro, score os mais baixos. O padrão é -score.
    -scorescore
  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos lead, com total_count.

Erros

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

O objeto competitor account

A conta do X de um concorrente. O Gemlead lê quem comenta nos posts dela e pontua essas pessoas como leads.

Atributos

  • objectstring
    Sempre competitor_account.
  • usernamestring
    O username no X, sem o @.
  • persona_idstring
    A persona para a qual ela encontra leads.
  • statsobject
    O que ela trouxe até agora.
  • first_found_atstring ou null
    Quando ela encontrou o primeiro lead, em ISO 8601.
O objeto competitor account
{
  "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"
}

Listar contas concorrentes

GET/v1/personas/:persona_id/competitor_accountsScope readMCPlist_persona_items

Retorna as contas concorrentes da persona, cada uma com os leads encontrados, pontuados e quentes.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Retorno

Uma lista de objetos competitor account.

Erros

GET/v1/personas/:persona_id/competitor_accounts
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "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
}

Adicionar contas concorrentes

POST/v1/personas/:persona_id/competitor_accountsScope writeMCPedit_persona_items

Adiciona contas concorrentes a uma persona. O Gemlead lê quem comenta nos posts delas e pontua essas pessoas.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • usernamesarray de stringsObrigatório
    De 1 a 50 contas concorrentes a adicionar, 100 no total numa persona. Cada uma é um username do X, com ou sem o @.

Retorno

As contas concorrentes da persona, uma lista de objetos competitor account.

Erros

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"]
  }'
Resposta200
{
  "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
}

Remover contas concorrentes

POST/v1/personas/:persona_id/competitor_accounts/removeScope writeMCPedit_persona_items

Remove contas concorrentes de uma persona. Os leads que elas encontraram continuam lá.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros do corpo

  • usernamesarray de stringsObrigatório
    As contas concorrentes a remover, como aparecem na lista.

Retorno

As contas concorrentes que restam na persona, uma lista de objetos competitor account.

Erros

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"]
  }'
Resposta200
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Listar os leads de uma conta concorrente

GET/v1/personas/:persona_id/competitor_accounts/leadsScope readMCPlist_item_leads

Retorna os leads que uma conta concorrente encontrou, do maior score para o menor.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Parâmetros de consulta

  • usernamestringObrigatório
    O username do concorrente no X, como aparece na lista.
  • orderstring
    -score coloca os melhores leads primeiro, score os mais baixos. O padrão é -score.
    -scorescore
  • limitinteger
    Quantos objetos retornar, de 1 a 100. O padrão é 25.
  • cursorstring
    O next_cursor da página anterior, para obter a página seguinte. Veja Paginação.

Retorno

Uma lista de objetos lead, com total_count.

Erros

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

O objeto source suggestion

Uma conta do X que a IA escolheu como fonte para uma persona, com o motivo e o que ler nela.

Atributos

  • objectstring
    Sempre source_suggestion.
  • profileobject
    O perfil dela no X, como no objeto X profile.
  • methodstring
    O que ler nela.
    followingcompetitor_followers
  • reasonstring ou null
    Por que a IA escolheu essa conta.
  • seed_adviceobject ou null
    A análise que o próprio Gemlead faz da conta.
O objeto source suggestion
{
  "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"
  }
}

Sugerir fontes

GET/v1/personas/:persona_id/source_suggestionsScope readMCPsuggest_sources

Pede à IA contas do X para adicionar como fontes, escolhidas a partir da descrição, das palavras-chave e dos concorrentes da persona.

Parâmetros de caminho

  • persona_idstringObrigatório
    O ID da persona.

Retorno

Uma lista de objetos source suggestion.

Erros

GET/v1/personas/:persona_id/source_suggestions
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/source_suggestions \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Resposta200
{
  "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
}

O objeto X profile

Uma conta do X lida ao vivo com a sua sessão do X, antes de você adicioná-la como fonte ou como concorrente.

Atributos

  • objectstring
    Sempre x_profile.
  • x_user_idstring
    O ID numérico da conta do X, como string.
  • usernamestring
    O username no X, sem o @.
  • namestring
    O nome de exibição.
  • biostring
    A bio do perfil.
  • followers_countinteger
    Seguidores no X.
  • following_countinteger
    Contas que ela segue no X.
  • locationstring
    A localização escrita no perfil.
  • websitestring
    O site que aparece no perfil.
  • profile_image_urlstring
    A URL da foto do perfil.
  • verifiedboolean
    Indica se a conta tem o selo de verificado.
  • urlstring
    A URL do perfil no X.
  • can_dmboolean ou null
    Indica se a sua conta pode mandar DM para ela, quando o X informa.
  • joined_atstring ou null
    Quando a conta foi criada no X, em ISO 8601.
  • seed_adviceobject
    Só com o parâmetro persona. O quanto ela vale como fonte, uma vez para cada forma de leitura.
O objeto X profile
{
  "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"
}

Consultar um perfil do X

GET/v1/x_profiles/:usernameScope readMCPlookup_x_profile

Lê um perfil do X ao vivo com a sua sessão do X. Com persona, também diz o quanto a conta vale como fonte para ela.

Parâmetros de caminho

  • usernamestringObrigatório
    O username do X, com ou sem o @.

Parâmetros de consulta

  • personastring
    Um ID de persona, para obter o seed_advice dela.

Retorno

Um objeto X profile.

Erros

  • 400x_profile_not_found
    O X não tem um perfil que possa ser lido com este username.
  • 409x_session_expired
    A sessão da conta do X expirou. Reconecte a conta no app e tente de novo.
  • 502upstream_unavailable
    O X ou um serviço do Gemlead não respondeu. Nada mudou, tente de novo em um minuto.
GET/v1/x_profiles/:username
curl -G https://gemlead.ai/api/v1/x_profiles/pickswithmike \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d persona=lvWBPnytpS
Resposta200
{
  "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"
    }
  }
}
Receba as novidades do Gemlead
direto no seu e-mail.
Assinar
Ao assinar, você aceita a nossa Política de Privacidade e concorda em receber novidades da nossa empresa.
Gemlead
Produto
Começar
Entrar
Para quem
Agentes de IA
Recursos
Preços
Afiliados
FAQ
Recursos
Compradores, 24/7Os quentes primeiro+60% de respostasDMs sob medidaTudo numa caixa sóSeu closer de IAEscale sem limitesAPI, MCP, webhooksPergunte ao Gemlead
Conteúdo
InícioAPIBlog
Jurídico
Termos
Privacidade
© 2026 Gemlead, Inc. Todos os direitos reservados.
Português