Gemlead
Docs
Se connecter
Obtenir ta clé API

Référence API

Sources

Les sources décident où Gemlead cherche les leads d'un persona. Une source est un compte X dont on lit les abonnements ou les abonnés. Une recherche par mots-clés trouve les auteurs des posts qui correspondent. Un compte concurrent amène les gens qui commentent ses posts.

Chacun montre les leads trouvés, scorés et chauds, pour que tu gardes ce qui marche. Consulte d'abord un profil X pour voir s'il ferait une bonne source.

Endpoints

L'objet source

Un compte X dont Gemlead lit le réseau pour trouver les leads d'un persona. Il lit ses abonnements, ses abonnés, ou les deux.

Attributs

  • idstring
    Identifiant unique de la source.
  • objectstring
    Toujours source.
  • persona_idstring
    Le persona pour lequel elle trouve des leads.
  • methodstring
    competitor_followers quand seuls ses abonnés sont lus, sinon following.
    followingcompetitor_followers
  • profileobject
    Le profil X de la source.
  • statusstring
    Où en est sa lecture.
    pendingscrapingscoringdonefailedskipped
  • pausedboolean
    Si tu l'as mise en pause.
  • errorstring ou null
    Pourquoi sa lecture a échoué, le cas échéant.
  • read_followingboolean
    Si ses abonnements sont lus.
  • read_followersboolean
    Si ses abonnés sont lus.
  • score_selfboolean
    Si le compte de la source est aussi scoré comme lead.
  • self_lead_idstring ou null
    Le lead du compte de la source, une fois scoré.
  • origin_lead_idstring ou null
    Le lead d'où elle vient, quand tu l'as créée avec Faire d'un lead une source.
  • statsobject
    Ce qu'elle a rapporté jusqu'ici.
  • last_activity_atstring ou null
    Date du dernier lead qu'elle a rapporté, en ISO 8601.
  • last_scraped_atstring ou null
    Date de sa dernière lecture, en ISO 8601.
  • created_atstring
    Date d'ajout, en ISO 8601.
L'objet 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"
}

Lister les sources

GET/v1/personas/:persona_id/sourcesScope readMCPlist_sources

Renvoie les sources du persona avec leurs stats.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres de requête

  • pausedboolean
    true pour les sources en pause uniquement, false pour celles qui sont actives.
  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets source.

Erreurs

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

Récupérer une source

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

Renvoie une source avec ses stats.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

Un objet source.

Erreurs

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

Ajouter une source

POST/v1/personas/:persona_id/sourcesScope writeMCPadd_source

Ajoute un compte X comme source. Les meilleures sources sont des gens qui ressemblent à tes acheteurs, car ils suivent surtout leurs pairs. Les abonnés d'un concurrent s'intéressent déjà à des produits comme le tien.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres du corps

  • usernamestringObligatoire
    Un nom d'utilisateur X, de 1 à 15 lettres, chiffres ou _, avec ou sans le @.
  • read_followingboolean
    Lire ses abonnements, les gens qui lui ressemblent. true par défaut.
  • read_followersboolean
    Lire ses abonnés, l'audience d'un concurrent par exemple. false par défaut.
  • score_selfboolean
    Scorer aussi le compte de la source comme lead. true par défaut.

Renvoie

Le nouvel objet source.

Erreurs

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
  }'
Réponse200
{
  "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"
}

Modifier une source

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

Modifie ce que Gemlead lit sur la source.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Paramètres du corps

  • read_followingboolean
    Lire ses abonnements, les gens qui lui ressemblent.
  • read_followersboolean
    Lire ses abonnés, l'audience d'un concurrent par exemple.
  • score_selfboolean
    Scorer aussi le compte de la source comme lead.

Renvoie

L'objet source à jour.

Erreurs

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
  }'
Réponse200
{
  "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"
}

Mettre une source en pause

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

Arrête de lire la source pour le moment. Ses leads sont conservés.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

L'objet source.

Erreurs

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"
Réponse200
{
  "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"
}

Relancer une source

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

Reprend la lecture d'une source en pause.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

L'objet source.

Erreurs

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"
Réponse200
{
  "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"
}

Ignorer une source

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

Arrête une source définitivement et la marque comme terminée, quand elle amène les mauvaises personnes.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

L'objet source.

Erreurs

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"
Réponse200
{
  "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"
}

Actualiser une source

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

Relit le profil X de la source, pour un nouveau nom, une nouvelle photo ou un nouveau nombre d'abonnés.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

L'objet source.

Erreurs

  • 404resource_missing
    Aucune source avec cet ID sur le compte de la clé.
  • 409x_session_expired
    La session du compte X a expiré. Reconnecte-le dans l'app, puis réessaie.
  • 502upstream_unavailable
    X ou un service Gemlead n'a pas répondu. Rien n'a changé, réessaie dans une minute.
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"
Réponse200
{
  "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"
}

Scorer une source

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

Score le compte X de la source comme lead du persona. Coûte jusqu'à 2 crédits par lead : 1 pour le premier tri, 1 de plus pour le score approfondi s'il passe ce tri.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

L'objet source.

Erreurs

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"
Réponse200
{
  "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"
}

Supprimer une source

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

Retire une source et les leads qu'elle a trouvés et qui ne sont passés par aucune campagne.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Renvoie

Un objet avec l'id de la source, deleted à true et le nombre deleted_leads.

Erreurs

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

Lister les leads d'une source

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

Renvoie les leads trouvés par une source, meilleur score en premier.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.
  • source_idstringObligatoire
    L'ID de la source.

Paramètres de requête

  • orderstring
    -score met les meilleurs leads en premier, score les plus bas. -score par défaut.
    -scorescore
  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets lead, avec total_count.

Erreurs

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
Réponse200
{
  "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
}

L'objet recherche par mots-clés

Une recherche que Gemlead lance sur X pour un persona. Les auteurs des posts trouvés sont scorés comme leads.

Attributs

  • objectstring
    Toujours search_query.
  • querystring
    La recherche, telle que tu la taperais sur X.
  • persona_idstring
    Le persona pour lequel elle trouve des leads.
  • statsobject
    Ce qu'elle a rapporté jusqu'ici.
  • first_found_atstring ou null
    Date du premier lead qu'elle a trouvé, en ISO 8601.
L'objet recherche par mots-clés
{
  "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"
}

Lister les recherches par mots-clés

GET/v1/personas/:persona_id/search_queriesScope readMCPlist_persona_items

Renvoie les recherches par mots-clés du persona, chacune avec ses leads trouvés, scorés et chauds.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Renvoie

Une liste d'objets recherche par mots-clés.

Erreurs

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

Ajouter des recherches par mots-clés

POST/v1/personas/:persona_id/search_queriesScope writeMCPedit_persona_items

Ajoute des recherches par mots-clés à un persona. Gemlead cherche sur X les posts qui les contiennent et score leurs auteurs.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres du corps

  • queriestableau de stringsObligatoire
    De 1 à 50 recherches par mots-clés à ajouter, 500 au total sur un persona. Chacune s'écrit comme tu la taperais sur X, de 2 à 200 caractères.

Renvoie

Les recherches par mots-clés du persona, une liste d'objets recherche par mots-clés.

Erreurs

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"]
  }'
Réponse200
{
  "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
}

Retirer des recherches par mots-clés

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

Retire des recherches par mots-clés d'un persona. Les leads qu'elles ont trouvés sont conservés.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres du corps

  • queriestableau de stringsObligatoire
    Les recherches par mots-clés à retirer, telles que la liste les renvoie.

Renvoie

Les recherches par mots-clés restantes du persona, une liste d'objets recherche par mots-clés.

Erreurs

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"]
  }'
Réponse200
{
  "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
}

Lister les leads d'une recherche par mots-clés

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

Renvoie les leads trouvés par une recherche par mots-clés, meilleur score en premier.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres de requête

  • querystringObligatoire
    La recherche par mots-clés, telle que la liste la renvoie.
  • orderstring
    -score met les meilleurs leads en premier, score les plus bas. -score par défaut.
    -scorescore
  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets lead, avec total_count.

Erreurs

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
Réponse200
{
  "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
}

L'objet compte concurrent

Le compte X d'un concurrent. Gemlead lit qui commente ses posts et les score comme leads.

Attributs

  • objectstring
    Toujours competitor_account.
  • usernamestring
    Le nom d'utilisateur X, sans le @.
  • persona_idstring
    Le persona pour lequel elle trouve des leads.
  • statsobject
    Ce qu'elle a rapporté jusqu'ici.
  • first_found_atstring ou null
    Date du premier lead qu'elle a trouvé, en ISO 8601.
L'objet compte concurrent
{
  "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"
}

Lister les comptes concurrents

GET/v1/personas/:persona_id/competitor_accountsScope readMCPlist_persona_items

Renvoie les comptes concurrents du persona, chacun avec ses leads trouvés, scorés et chauds.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Renvoie

Une liste d'objets compte concurrent.

Erreurs

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

Ajouter des comptes concurrents

POST/v1/personas/:persona_id/competitor_accountsScope writeMCPedit_persona_items

Ajoute des comptes concurrents à un persona. Gemlead lit qui commente leurs posts et les score.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres du corps

  • usernamestableau de stringsObligatoire
    De 1 à 50 comptes concurrents à ajouter, 100 au total sur un persona. Chacun est un nom d'utilisateur X, avec ou sans le @.

Renvoie

Les comptes concurrents du persona, une liste d'objets compte concurrent.

Erreurs

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"]
  }'
Réponse200
{
  "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
}

Retirer des comptes concurrents

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

Retire des comptes concurrents d'un persona. Les leads qu'ils ont trouvés sont conservés.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres du corps

  • usernamestableau de stringsObligatoire
    Les comptes concurrents à retirer, tels que la liste les renvoie.

Renvoie

Les comptes concurrents restants du persona, une liste d'objets compte concurrent.

Erreurs

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

Lister les leads d'un compte concurrent

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

Renvoie les leads trouvés par un compte concurrent, meilleur score en premier.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Paramètres de requête

  • usernamestringObligatoire
    Le nom d'utilisateur X du concurrent, tel que la liste le renvoie.
  • orderstring
    -score met les meilleurs leads en premier, score les plus bas. -score par défaut.
    -scorescore
  • limitinteger
    Nombre d'objets à renvoyer, de 1 à 100. 25 par défaut.
  • cursorstring
    Le next_cursor de la page précédente, pour obtenir la suivante. Voir Pagination.

Renvoie

Une liste d'objets lead, avec total_count.

Erreurs

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
Réponse200
{
  "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
}

L'objet suggestion de source

Un compte X que l'IA a choisi comme source pour un persona, avec la raison et la façon de le lire.

Attributs

  • objectstring
    Toujours source_suggestion.
  • profileobject
    Son profil X, comme dans l'objet profil X.
  • methodstring
    Ce qu'il faut y lire.
    followingcompetitor_followers
  • reasonstring ou null
    Pourquoi l'IA l'a choisi.
  • seed_adviceobject ou null
    La vérification du compte par Gemlead.
L'objet suggestion de source
{
  "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"
  }
}

Suggérer des sources

GET/v1/personas/:persona_id/source_suggestionsScope readMCPsuggest_sources

Demande à l'IA des comptes X à ajouter comme sources, choisis d'après la description, les mots-clés et les concurrents du persona.

Paramètres de chemin

  • persona_idstringObligatoire
    L'ID du persona.

Renvoie

Une liste d'objets suggestion de source.

Erreurs

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

L'objet profil X

Un compte X lu en direct avec ta session X, avant de l'ajouter comme source ou concurrent.

Attributs

  • objectstring
    Toujours x_profile.
  • x_user_idstring
    L'ID numérique du compte X, en chaîne de caractères.
  • usernamestring
    Le nom d'utilisateur X, sans le @.
  • namestring
    Le nom affiché.
  • biostring
    La bio du profil.
  • followers_countinteger
    Abonnés sur X.
  • following_countinteger
    Abonnements sur X.
  • locationstring
    La localisation indiquée sur le profil.
  • websitestring
    Le site web du profil.
  • profile_image_urlstring
    L'URL de la photo de profil.
  • verifiedboolean
    Si le compte a un badge vérifié.
  • urlstring
    L'URL du profil sur X.
  • can_dmboolean ou null
    Si ton compte peut lui envoyer un DM, quand X l'indique.
  • joined_atstring ou null
    Date de création du compte sur X, en ISO 8601.
  • seed_adviceobject
    Avec le paramètre persona uniquement. La qualité du compte comme source, pour chaque façon de le lire.
L'objet profil X
{
  "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"
}

Consulter un profil X

GET/v1/x_profiles/:usernameScope readMCPlookup_x_profile

Lit un profil X en direct avec ta session X. Avec persona, il indique aussi la qualité du compte comme source pour ce persona.

Paramètres de chemin

  • usernamestringObligatoire
    Le nom d'utilisateur X, avec ou sans le @.

Paramètres de requête

  • personastring
    Un ID de persona, pour obtenir le seed_advice correspondant.

Renvoie

Un objet profil X.

Erreurs

GET/v1/x_profiles/:username
curl -G https://gemlead.ai/api/v1/x_profiles/pickswithmike \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d persona=lvWBPnytpS
Réponse200
{
  "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"
    }
  }
}
Reçois les nouveautés de Gemlead
directement dans ta boîte mail.
S'abonner
En t'abonnant, tu acceptes notre Politique de confidentialité et l'envoi de nos nouveautés.
Gemlead
Produit
Commencer
Se connecter
Pour qui
Agents IA
Fonctionnalités
Tarifs
Affiliation
FAQ
Fonctionnalités
Tes acheteurs, 24/7Leads chauds d'abord60 %+ de réponsesDes DM sur mesureTous les DM, une inboxTon closer IAScale sans limiteAPI, MCP, webhooksDemande à Gemlead
Ressources
AccueilAPIBlog
Juridique
Conditions
Confidentialité
© 2026 Gemlead, Inc. Tous droits réservés.
Français