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

Referencia de la API

Leads

Los leads son los perfiles que Gemlead encuentra en X para tus buyer personas. Dana AI puntúa a cada uno de 0 a 100, y un lead está caliente a partir de 60. Lístalos con filtros, añádeles tus propios metadatos, como un ID de CRM, o actúa sobre uno como harías en la app.

Endpoints

El objeto lead

Alguien que Gemlead encontró en X para uno de tus buyer personas, con la puntuación que le dio Dana AI y la etapa de tu prospección en la que está.

Atributos

  • idstring
    Identificador único del lead.
  • objectstring
    Siempre lead.
  • profileobject
    El perfil de X del lead.
  • scoreinteger o null
    Cuánto encaja el lead con tu buyer persona, de 0 a 100. Null hasta que se puntúe.
  • score_reasonstring o null
    Por qué el lead obtuvo esta puntuación, en una o dos frases.
  • hotboolean
    True si la puntuación es de 60 o más.
  • statusstring
    En qué punto de tu pipeline está el lead.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • personaobject o null
    El buyer persona para el que se encontró el lead.
  • campaignobject o null
    La campaña en la que está el lead, si la hay.
  • conversation_idstring o null
    La conversación con el lead, cuando ya existe. Úsala con Obtener una conversación.
  • locked_toobject o null
    La única cuenta de X del propietario a la que se reserva este perfil. Un lead va a una sola cuenta de X, así que las demás nunca lo contactan. Null mientras ninguna cuenta retenga el lead.
  • found_atstring
    Cuándo encontró Gemlead el lead, en ISO 8601.
  • scored_atstring o null
    Cuándo se puntuó el lead, en ISO 8601.
  • updated_atstring
    Cuándo cambió el lead por última vez, en ISO 8601.
  • metadataobject
    Tus propios pares clave-valor, definidos con Actualizar un lead.
El objeto lead
{
  "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": {}
}

Listar leads

GET/v1/leadsScope readMCPsearch_leads

Devuelve tus leads, por defecto primero los puntuados más recientemente. Combina filtros para obtener justo los leads que quieres.

Parámetros de consulta

  • personastring
    Solo los leads del buyer persona con este ID.
  • statusstring
    Solo los leads con estos estados, separados por comas, como scored,in_campaign.
    pendingscoringscoredin_campaigncontactedin_conversationclosed
  • score_mininteger
    Solo los leads con esta puntuación o más, de 0 a 100.
  • score_maxinteger
    Solo los leads con esta puntuación o menos, de 0 a 100.
  • hotboolean
    true para los leads con una puntuación de 60 o más, false para los demás.
  • scored_afterstring
    Solo los leads puntuados después de esta fecha, en ISO 8601.
  • scored_beforestring
    Solo los leads puntuados antes de esta fecha, en ISO 8601.
  • found_afterstring
    Solo los leads encontrados después de esta fecha, en ISO 8601.
  • found_beforestring
    Solo los leads encontrados antes de esta fecha, en ISO 8601.
  • orderstring
    El criterio de orden. Por defecto -scored_at, primero los puntuados más recientemente.
    -scored_at-score-found_at
  • 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.

Errores

  • 400parameter_invalid
    Un parámetro tiene un valor que la API no acepta. param lo indica.
GET/v1/leads
curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -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"
}

Obtener un lead

GET/v1/leads/:idScope readMCPget_lead

Devuelve un lead.

Parámetros de ruta

  • idstringObligatorio
    El ID del lead.

Devuelve

Un objeto lead.

Errores

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

Actualizar un lead

PATCH/v1/leads/:idScope writeMCPupdate_lead

Define tus propios metadatos en un lead, o lo cierra cuando terminas con él. Cerrar un lead detiene los pasos de campaña que aún tenía pendientes, así que Gemlead deja de escribirle.

Parámetros de ruta

  • idstringObligatorio
    El ID del lead.

Parámetros del cuerpo

  • metadataobject
    Pares clave-valor que se fusionan con los metadatos del lead. Claves de hasta 40 letras, cifras, _ o -, valores de tipo string de hasta 500 caracteres, 20 claves como máximo. Pon una clave en null o en un string vacío para quitarla, o metadata en null para borrarlas todas.
  • statusstring
    Ponlo en closed para cerrar el lead.
    closed

Devuelve

El objeto lead actualizado.

Errores

PATCH/v1/leads/:id
curl -X PATCH https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_id": "hs_48213"
    }
  }'
Respuesta200
{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "profile": {
    "x_user_id": "1460283925",
    "username": "jane_builds",
    "name": "Jane Doe",
    "bio": "Runs a paid trading community. Daily setups, no hype.",
    "followers_count": 12400,
    "following_count": 380,
    "location": "Austin, TX",
    "website": "https://janedoe.com",
    "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
    "verified": true,
    "url": "https://x.com/jane_builds"
  },
  "score": 86,
  "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
  "hot": true,
  "status": "scored",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "campaign": null,
  "conversation_id": null,
  "locked_to": null,
  "found_at": "2026-11-05T14:02:11.482Z",
  "scored_at": "2026-11-05T14:03:40.117Z",
  "updated_at": "2026-11-05T14:03:40.117Z",
  "metadata": {
    "crm_id": "hs_48213"
  }
}

Volver a puntuar un lead

POST/v1/leads/:lead_id/rescoreScope writeMCPlead_action

Pide a Dana AI que vuelva a puntuar el lead según su buyer persona, por ejemplo después de editar la descripción 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

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

El objeto lead.

Errores

  • 404resource_missing
    No hay ningún lead 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.
POST/v1/leads/:lead_id/rescore
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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": {}
}

Actualizar el perfil de un lead

POST/v1/leads/:lead_id/refreshScope writeMCPlead_action

Vuelve a leer el perfil de X del lead, para tener al día su bio, su foto o su número de seguidores.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

El objeto lead actualizado.

Errores

  • 404resource_missing
    No hay ningún lead 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/leads/:lead_id/refresh
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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": {}
}

Seguir a un lead

POST/v1/leads/:lead_id/followScope writeMCPlead_action

Sigue al lead en X desde tu cuenta de X, al instante.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

El objeto lead.

Errores

  • 404resource_missing
    No hay ningún lead con este ID en la cuenta de la clave.
  • 400lead_without_x_id
    El lead no tiene ID de cuenta de X que seguir.
  • 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/leads/:lead_id/follow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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": {}
}

Dejar de seguir a un lead

POST/v1/leads/:lead_id/unfollowScope writeMCPlead_action

Deja de seguir al lead en X desde tu cuenta de X, al instante.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

El objeto lead.

Errores

  • 404resource_missing
    No hay ningún lead con este ID en la cuenta de la clave.
  • 400lead_without_x_id
    El lead no tiene ID de cuenta de X que dejar de seguir.
  • 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/leads/:lead_id/unfollow
curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "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": {}
}

Convertir un lead en fuente

POST/v1/leads/:lead_id/convert_to_sourceScope writeMCPconvert_lead_to_source

Convierte un buen lead en fuente de su buyer persona, para encontrar más perfiles como él. Gemlead lee a quién sigue, sus seguidores o quién comenta sus publicaciones.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Parámetros del cuerpo

  • methodstring
    following lee a quién sigue el lead, competitor_followers sus seguidores, competitor_comments quién comenta sus publicaciones. Por defecto following.
    followingcompetitor_followerscompetitor_comments

Devuelve

Un objeto con el lead_id, su persona_id, el method y la nueva fuente, o el nombre de usuario competitor_account para competitor_comments.

Errores

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

Eliminar un lead

DELETE/v1/leads/:lead_idScope writeMCPdelete_lead

Elimina un lead. Sale de tus listas, todas las campañas se detienen para él y Gemlead no vuelve a traer ese mismo perfil para este buyer persona. Para dejar a alguien fuera de todos tus buyer personas, añádelo a la lista de exclusión.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

Un objeto con el id del lead y deleted en true.

Errores

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

El objeto lead origin

Cómo encontró Gemlead un lead, la publicación que lo hizo aparecer y cada campaña en la que está.

Atributos

  • objectstring
    Siempre lead_origin.
  • lead_idstring
    El ID del lead.
  • personaobject o null
    El buyer persona para el que se encontró.
  • methodstring o null
    Cómo se encontró.
    followingkeywordscompetitor_followerscompetitor_comments
  • found_querystring o null
    La búsqueda por palabras clave que lo encontró, para keywords.
  • source_usernamestring o null
    La fuente o la cuenta de competidor a través de la que se encontró.
  • found_postobject o null
    La publicación que hizo aparecer el lead, si la hubo.
  • campaignsarray de objects
    Las campañas en las que está el lead, cada una con su id, su name, el status del lead en ella, el method de la campaña y el step en el que está el lead.
El objeto lead origin
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}

Obtener el origen de un lead

GET/v1/leads/:lead_id/originScope readMCPget_lead_origin

Devuelve cómo encontró Gemlead el lead, la publicación que lo hizo aparecer y cada campaña en la que está, con el paso en el que se encuentra.

Parámetros de ruta

  • lead_idstringObligatorio
    El ID del lead.

Devuelve

Un objeto lead origin.

Errores

GET/v1/leads/:lead_id/origin
curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Respuesta200
{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}
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