Gemlead
Docs
Iniciar sesión
Obtén tu clave API

Referencia de la API

Fuentes

Las fuentes deciden dónde busca Gemlead los leads de un buyer persona. Una fuente es una cuenta de X cuyos seguidos o seguidores se leen. Una búsqueda por palabras clave encuentra a los autores de las publicaciones que coinciden. Una cuenta de competidor trae a la gente que comenta sus publicaciones.

Cada una muestra sus leads encontrados, puntuados y calientes, para que te quedes con lo que funciona. Consulta antes un perfil de X para ver si sería una buena fuente.

Endpoints

El objeto source

Una cuenta de X cuya red lee Gemlead para encontrar los leads de un buyer persona. Lee las cuentas que sigue, sus seguidores o ambos.

Atributos

  • idstring
    Identificador único de la fuente.
  • objectstring
    Siempre source.
  • persona_idstring
    El buyer persona para el que encuentra leads.
  • methodstring
    competitor_followers si solo se leen sus seguidores, following en los demás casos.
    followingcompetitor_followers
  • profileobject
    El perfil de X de la fuente.
  • statusstring
    En qué punto está su lectura.
    pendingscrapingscoringdonefailedskipped
  • pausedboolean
    Si la pausaste.
  • errorstring o null
    Por qué falló su lectura, si falló.
  • read_followingboolean
    Si se leen las cuentas que sigue.
  • read_followersboolean
    Si se leen sus seguidores.
  • score_selfboolean
    Si la propia cuenta de la fuente también se puntúa como lead.
  • self_lead_idstring o null
    El lead de la propia cuenta de la fuente, una vez puntuado.
  • origin_lead_idstring o null
    El lead del que viene, si la creaste con Convertir un lead en fuente.
  • statsobject
    Lo que ha traído hasta ahora.
  • last_activity_atstring o null
    Cuándo trajo un lead por última vez, en ISO 8601.
  • last_scraped_atstring o null
    Cuándo se leyó por última vez, en ISO 8601.
  • created_atstring
    Cuándo se añadió, en ISO 8601.
El 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 fuentes

GET/v1/personas/:persona_id/sourcesScope readMCPlist_sources

Devuelve las fuentes del buyer persona con sus estadísticas.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros de consulta

  • pausedboolean
    true solo para las fuentes en pausa, false para las activas.
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos source.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
GET/v1/personas/:persona_id/sources
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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
}

Obtener una fuente

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

Devuelve una fuente con sus estadísticas.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

Un objeto source.

Errores

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

Añadir una fuente

POST/v1/personas/:persona_id/sourcesScope writeMCPadd_source

Añade una cuenta de X como fuente. Las mejores son cuentas parecidas a tus compradores, porque siguen a muchos de sus pares. Los seguidores de un competidor ya se interesan por productos como el tuyo.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • usernamestringObligatorio
    Un nombre de usuario de X, de 1 a 15 letras, cifras o _, con o sin la @.
  • read_followingboolean
    Leer las cuentas que sigue, la gente que se le parece. Por defecto true.
  • read_followersboolean
    Leer sus seguidores, por ejemplo la audiencia de un competidor. Por defecto false.
  • score_selfboolean
    Puntuar también la propia cuenta de la fuente como lead. Por defecto true.

Devuelve

El nuevo objeto source.

Errores

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

Actualizar una fuente

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

Cambia lo que Gemlead lee en la fuente.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Parámetros del cuerpo

  • read_followingboolean
    Leer las cuentas que sigue, la gente que se le parece.
  • read_followersboolean
    Leer sus seguidores, por ejemplo la audiencia de un competidor.
  • score_selfboolean
    Puntuar también la propia cuenta de la fuente como lead.

Devuelve

El objeto source actualizado.

Errores

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
  }'
Respuesta200
{
  "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 una fuente

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

Deja de leer la fuente por ahora. Sus leads se conservan.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

El objeto source.

Errores

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

Reanudar una fuente

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

Vuelve a leer una fuente en pausa.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

El objeto source.

Errores

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

Descartar una fuente

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

Detiene una fuente definitivamente y la da por terminada, cuando trae a la gente equivocada.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

El objeto source.

Errores

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

Actualizar el perfil de una fuente

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

Vuelve a leer el perfil de X de la fuente, para tener al día su nombre, su foto o su número de seguidores.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

El objeto source.

Errores

  • 404resource_missing
    No hay ninguna fuente con este ID en la cuenta de la clave.
  • 409x_session_expired
    La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.
  • 502upstream_unavailable
    X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un 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"
Respuesta200
{
  "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"
}

Puntuar una fuente

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

Puntúa la propia cuenta de X de la fuente como lead del buyer persona. Usa hasta 2 créditos por lead: 1 por la primera pasada y 1 más por la puntuación a fondo si la supera.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

El objeto source.

Errores

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

Eliminar una fuente

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

Quita una fuente y los leads que encontró y que ninguna campaña trabajó.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Devuelve

Un objeto con el id de la fuente, deleted en true y el total de deleted_leads.

Errores

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

Listar los leads de una fuente

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

Devuelve los leads que encontró una fuente, primero los de mejor puntuación.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.
  • source_idstringObligatorio
    El ID de la fuente.

Parámetros de consulta

  • orderstring
    -score pone primero los mejores leads, score los de menor puntuación. Por defecto -score.
    -scorescore
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos lead, con total_count.

Errores

  • 404resource_missing
    No hay ninguna fuente con este ID en la cuenta de la clave.
  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
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
Respuesta200
{
  "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
}

El objeto keyword search

Una búsqueda que Gemlead hace en X para un buyer persona. Los autores de las publicaciones que encuentra se puntúan como leads.

Atributos

  • objectstring
    Siempre search_query.
  • querystring
    La búsqueda, tal como la escribirías en X.
  • persona_idstring
    El buyer persona para el que encuentra leads.
  • statsobject
    Lo que ha traído hasta ahora.
  • first_found_atstring o null
    Cuándo encontró su primer lead, en ISO 8601.
El 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 búsquedas por palabras clave

GET/v1/personas/:persona_id/search_queriesScope readMCPlist_persona_items

Devuelve las búsquedas por palabras clave del buyer persona, cada una con sus leads encontrados, puntuados y calientes.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Una lista de objetos keyword search.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:persona_id/search_queries
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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
}

Añadir búsquedas por palabras clave

POST/v1/personas/:persona_id/search_queriesScope writeMCPedit_persona_items

Añade búsquedas por palabras clave a un buyer persona. Gemlead busca en X publicaciones que las contengan y puntúa a sus autores.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • queriesarray de stringsObligatorio
    De 1 a 50 búsquedas por palabras clave que añadir, 500 en total por buyer persona. Cada una es una búsqueda tal como la escribirías en X, de 2 a 200 caracteres.

Devuelve

Las búsquedas por palabras clave del buyer persona, una lista de objetos keyword search.

Errores

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

Quitar búsquedas por palabras clave

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

Quita búsquedas por palabras clave de un buyer persona. Los leads que encontraron se conservan.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • queriesarray de stringsObligatorio
    Las búsquedas por palabras clave que quitar, tal como aparecen en la lista.

Devuelve

Las búsquedas por palabras clave que le quedan al buyer persona, una lista de objetos keyword search.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 404resource_missing
    Una de ellas no está entre las búsquedas por palabras clave del buyer persona.
  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
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"]
  }'
Respuesta200
{
  "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 los leads de una búsqueda por palabras clave

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

Devuelve los leads que encontró una búsqueda por palabras clave, primero los de mejor puntuación.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros de consulta

  • querystringObligatorio
    La búsqueda por palabras clave, tal como aparece en la lista.
  • orderstring
    -score pone primero los mejores leads, score los de menor puntuación. Por defecto -score.
    -scorescore
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos lead, con total_count.

Errores

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

El objeto competitor account

La cuenta de X de un competidor. Gemlead lee quién comenta sus publicaciones y los puntúa como leads.

Atributos

  • objectstring
    Siempre competitor_account.
  • usernamestring
    El nombre de usuario de X, sin la @.
  • persona_idstring
    El buyer persona para el que encuentra leads.
  • statsobject
    Lo que ha traído hasta ahora.
  • first_found_atstring o null
    Cuándo encontró su primer lead, en ISO 8601.
El 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 cuentas de competidores

GET/v1/personas/:persona_id/competitor_accountsScope readMCPlist_persona_items

Devuelve las cuentas de competidores del buyer persona, cada una con sus leads encontrados, puntuados y calientes.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Una lista de objetos competitor account.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
GET/v1/personas/:persona_id/competitor_accounts
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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
}

Añadir cuentas de competidores

POST/v1/personas/:persona_id/competitor_accountsScope writeMCPedit_persona_items

Añade cuentas de competidores a un buyer persona. Gemlead lee quién comenta sus publicaciones y los puntúa.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • usernamesarray de stringsObligatorio
    De 1 a 50 cuentas de competidores que añadir, 100 en total por buyer persona. Cada una es un nombre de usuario de X, con o sin la @.

Devuelve

Las cuentas de competidores del buyer persona, una lista de objetos competitor account.

Errores

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

Quitar cuentas de competidores

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

Quita cuentas de competidores de un buyer persona. Los leads que encontraron se conservan.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros del cuerpo

  • usernamesarray de stringsObligatorio
    Las cuentas de competidores que quitar, tal como aparecen en la lista.

Devuelve

Las cuentas de competidores que le quedan al buyer persona, una lista de objetos competitor account.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 404resource_missing
    Una de ellas no está entre las cuentas de competidores del buyer persona.
  • 400parameter_missing
    Falta un parámetro obligatorio. param lo indica.
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"]
  }'
Respuesta200
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Listar los leads de una cuenta de competidor

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

Devuelve los leads que encontró una cuenta de competidor, primero los de mejor puntuación.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Parámetros de consulta

  • usernamestringObligatorio
    El nombre de usuario de X del competidor, tal como aparece en la lista.
  • orderstring
    -score pone primero los mejores leads, score los de menor puntuación. Por defecto -score.
    -scorescore
  • limitinteger
    Cuántos objetos devolver, de 1 a 100. 25 por defecto.
  • cursorstring
    El next_cursor de la página anterior, para obtener la siguiente. Consulta Paginación.

Devuelve

Una lista de objetos lead, con total_count.

Errores

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

El objeto source suggestion

Una cuenta de X que la IA eligió como fuente para un buyer persona, con el motivo y cómo leerla.

Atributos

  • objectstring
    Siempre source_suggestion.
  • profileobject
    Su perfil de X, como en el objeto X profile.
  • methodstring
    Qué leer en ella.
    followingcompetitor_followers
  • reasonstring o null
    Por qué la eligió la IA.
  • seed_adviceobject o null
    La evaluación que hace Gemlead de la cuenta.
El 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 fuentes

GET/v1/personas/:persona_id/source_suggestionsScope readMCPsuggest_sources

Pide a la IA cuentas de X que añadir como fuentes, elegidas según la descripción, las palabras clave y los competidores del buyer persona.

Parámetros de ruta

  • persona_idstringObligatorio
    El ID del buyer persona.

Devuelve

Una lista de objetos source suggestion.

Errores

  • 404resource_missing
    No hay ningún buyer persona con este ID en la cuenta de la clave.
  • 502upstream_unavailable
    X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un minuto.
GET/v1/personas/:persona_id/source_suggestions
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/source_suggestions \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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
}

El objeto X profile

Una cuenta de X leída en directo con tu sesión de X, antes de añadirla como fuente o como competidor.

Atributos

  • objectstring
    Siempre x_profile.
  • x_user_idstring
    El ID numérico de la cuenta de X, como string.
  • usernamestring
    El nombre de usuario de X, sin la @.
  • namestring
    El nombre visible.
  • biostring
    La bio del perfil.
  • followers_countinteger
    Seguidores en X.
  • following_countinteger
    Cuentas que sigue en X.
  • locationstring
    La ubicación escrita en el perfil.
  • websitestring
    El sitio web del perfil.
  • profile_image_urlstring
    La URL de la foto de perfil.
  • verifiedboolean
    Si la cuenta tiene insignia de verificación.
  • urlstring
    La URL del perfil en X.
  • can_dmboolean o null
    Si tu cuenta puede enviarle un DM, cuando X lo indica.
  • joined_atstring o null
    Cuándo se creó la cuenta en X, en ISO 8601.
  • seed_adviceobject
    Solo con el parámetro persona. La calidad de la cuenta como fuente, una vez por cada forma de leerla.
El 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 un perfil de X

GET/v1/x_profiles/:usernameScope readMCPlookup_x_profile

Lee un perfil de X en directo con tu sesión de X. Con persona, también indica si la cuenta sería una buena fuente para ese buyer persona.

Parámetros de ruta

  • usernamestringObligatorio
    El nombre de usuario de X, con o sin la @.

Parámetros de consulta

  • personastring
    Un ID de buyer persona, para obtener su seed_advice.

Devuelve

Un objeto X profile.

Errores

  • 400x_profile_not_found
    X no tiene ningún perfil legible con este nombre de usuario.
  • 409x_session_expired
    La sesión de la cuenta de X caducó. Vuelve a conectarla en la app e inténtalo de nuevo.
  • 502upstream_unavailable
    X o un servicio de Gemlead no respondió. No ha cambiado nada, vuelve a intentarlo en un 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
Respuesta200
{
  "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"
    }
  }
}
Recibe las novedades de Gemlead
directamente en tu bandeja de entrada.
Suscribirme
Al suscribirte aceptas nuestra Política de privacidad y das tu consentimiento para recibir novedades de nuestra empresa.
Gemlead
Producto
Empezar
Iniciar sesión
Para quién
Agentes de IA
Funciones
Precios
Afiliados
FAQ
Funciones
Compradores 24/7Primero los calientes+60% de respuestasDM a medidaUna bandeja para todoTu closer con IAEscala sin límitesAPI, MCP, webhooksPregunta a Gemlead
Recursos
InicioAPIBlog
Legal
Términos
Privacidad
© 2026 Gemlead, Inc. Todos los derechos reservados.
Español