Gemlead
Docs
Accedi
Ottieni la tua chiave API

Riferimento API

Fonti

Le fonti decidono dove Gemlead cerca i lead di una buyer persona. Una fonte è un account X di cui si leggono gli account seguiti o i follower. Una ricerca per parola chiave trova gli autori dei post corrispondenti. Un account concorrente porta le persone che commentano i suoi post.

Ognuna mostra i suoi lead trovati, valutati e caldi, così tieni ciò che funziona. Consulta prima un profilo X per vedere quanto vale come fonte.

Endpoint

L'oggetto fonte

Un account X di cui Gemlead legge la rete per trovare i lead di una buyer persona. Legge gli account che segue, i suoi follower o entrambi.

Attributi

  • idstring
    Identificatore univoco della fonte.
  • objectstring
    Sempre source.
  • persona_idstring
    La buyer persona per cui trova lead.
  • methodstring
    competitor_followers quando si leggono solo i suoi follower, altrimenti following.
    followingcompetitor_followers
  • profileobject
    Il profilo X della fonte.
  • statusstring
    A che punto è la lettura.
    pendingscrapingscoringdonefailedskipped
  • pausedboolean
    Se l'hai messa in pausa.
  • errorstring o null
    Perché la lettura non è riuscita, se è successo.
  • read_followingboolean
    Se si leggono gli account che segue.
  • read_followersboolean
    Se si leggono i suoi follower.
  • score_selfboolean
    Se anche l'account stesso della fonte viene valutato come lead.
  • self_lead_idstring o null
    Il lead dell'account stesso della fonte, una volta valutato.
  • origin_lead_idstring o null
    Il lead da cui è nata, quando l'hai creata con Trasforma un lead in una fonte.
  • statsobject
    Cosa ha portato finora.
  • last_activity_atstring o null
    Quando ha portato l'ultimo lead, ISO 8601.
  • last_scraped_atstring o null
    Quando è stata letta l'ultima volta, ISO 8601.
  • created_atstring
    Quando è stata aggiunta, ISO 8601.
L'oggetto fonte
{
  "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"
}

Elenca le fonti

GET/v1/personas/:persona_id/sourcesScope readMCPlist_sources

Restituisce le fonti della buyer persona con le loro statistiche.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri di query

  • pausedboolean
    true solo per le fonti in pausa, false per quelle attive.
  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti fonte.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
GET/v1/personas/:persona_id/sources
curl https://gemlead.ai/api/v1/personas/lvWBPnytpS/sources \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}

Recupera una fonte

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

Restituisce una fonte con le sue statistiche.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

Un oggetto fonte.

Errori

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

Aggiungi una fonte

POST/v1/personas/:persona_id/sourcesScope writeMCPadd_source

Aggiunge un account X come fonte. Le migliori sono persone simili ai tuoi acquirenti, perché tra gli account che seguono ci sono tanti loro pari. I follower di un concorrente sono già interessati a prodotti come il tuo.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • usernamestringObbligatorio
    Uno username X, da 1 a 15 lettere, cifre o _, con o senza la @.
  • read_followingboolean
    Legge gli account che segue, le persone che gli somigliano. Di default true.
  • read_followersboolean
    Legge i suoi follower, per esempio il pubblico di un concorrente. Di default false.
  • score_selfboolean
    Valuta anche l'account stesso della fonte come lead. Di default true.

Restituisce

Il nuovo oggetto fonte.

Errori

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

Aggiorna una fonte

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

Cambia cosa legge Gemlead sulla fonte.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Parametri del body

  • read_followingboolean
    Legge gli account che segue, le persone che gli somigliano.
  • read_followersboolean
    Legge i suoi follower, per esempio il pubblico di un concorrente.
  • score_selfboolean
    Valuta anche l'account stesso della fonte come lead.

Restituisce

L'oggetto fonte aggiornato.

Errori

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

Metti in pausa una fonte

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

Smette di leggere la fonte per ora. I suoi lead restano.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

L'oggetto fonte.

Errori

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

Riprendi una fonte

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

Ricomincia a leggere una fonte in pausa.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

L'oggetto fonte.

Errori

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

Salta una fonte

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

Ferma definitivamente una fonte e la segna come completata, se porta le persone sbagliate.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

L'oggetto fonte.

Errori

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

Aggiorna il profilo di una fonte

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

Rilegge il profilo X della fonte, per un nuovo nome, una nuova foto o un nuovo numero di follower.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

L'oggetto fonte.

Errori

  • 404resource_missing
    Nessuna fonte con questo ID sull'account della chiave.
  • 409x_session_expired
    La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra 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"
Risposta200
{
  "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"
}

Valuta una fonte

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

Valuta l'account X stesso della fonte come lead della buyer persona. Usa fino a 2 crediti per lead: 1 per la prima valutazione, 1 in più per quella approfondita se il lead la supera.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

L'oggetto fonte.

Errori

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

Elimina una fonte

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

Rimuove una fonte e i lead che ha trovato su cui nessuna campagna ha lavorato.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Restituisce

Un oggetto con l'id della fonte, deleted impostato su true e il conteggio di deleted_leads.

Errori

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

Elenca i lead di una fonte

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

Restituisce i lead trovati da una fonte, dal punteggio più alto.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.
  • source_idstringObbligatorio
    L'ID della fonte.

Parametri di query

  • orderstring
    -score mette prima i lead migliori, score i più bassi. Di default -score.
    -scorescore
  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti lead, con total_count.

Errori

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
Risposta200
{
  "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'oggetto ricerca per parola chiave

Una ricerca che Gemlead esegue su X per una buyer persona. Gli autori dei post che trova vengono valutati come lead.

Attributi

  • objectstring
    Sempre search_query.
  • querystring
    La ricerca, come la scriveresti su X.
  • persona_idstring
    La buyer persona per cui trova lead.
  • statsobject
    Cosa ha portato finora.
  • first_found_atstring o null
    Quando ha trovato il suo primo lead, ISO 8601.
L'oggetto ricerca per parola chiave
{
  "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"
}

Elenca le ricerche per parola chiave

GET/v1/personas/:persona_id/search_queriesScope readMCPlist_persona_items

Restituisce le ricerche per parola chiave della buyer persona, ognuna con i suoi lead trovati, valutati e caldi.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un elenco di oggetti ricerca per parola chiave.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
GET/v1/personas/:persona_id/search_queries
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/search_queries \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}

Aggiungi ricerche per parola chiave

POST/v1/personas/:persona_id/search_queriesScope writeMCPedit_persona_items

Aggiunge ricerche per parola chiave a una buyer persona. Gemlead cerca su X i post che le contengono e ne valuta gli autori.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • queriesarray di stringsObbligatorio
    Da 1 a 50 ricerche per parola chiave da aggiungere, 500 in tutto per buyer persona. Ognuna è una ricerca come la scriveresti su X, da 2 a 200 caratteri.

Restituisce

Le ricerche per parola chiave della buyer persona, un elenco di oggetti ricerca per parola chiave.

Errori

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

Rimuovi ricerche per parola chiave

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

Rimuove ricerche per parola chiave da una buyer persona. I lead che hanno trovato restano.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • queriesarray di stringsObbligatorio
    Le ricerche per parola chiave da rimuovere, come sono elencate.

Restituisce

Le ricerche per parola chiave rimaste alla buyer persona, un elenco di oggetti ricerca per parola chiave.

Errori

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

Elenca i lead di una ricerca per parola chiave

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

Restituisce i lead trovati da una ricerca per parola chiave, dal punteggio più alto.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri di query

  • querystringObbligatorio
    La ricerca per parola chiave, come è elencata.
  • orderstring
    -score mette prima i lead migliori, score i più bassi. Di default -score.
    -scorescore
  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti lead, con total_count.

Errori

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
Risposta200
{
  "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'oggetto account concorrente

L'account X di un concorrente. Gemlead legge chi commenta i suoi post e ne valuta gli autori come lead.

Attributi

  • objectstring
    Sempre competitor_account.
  • usernamestring
    Lo username X, senza la @.
  • persona_idstring
    La buyer persona per cui trova lead.
  • statsobject
    Cosa ha portato finora.
  • first_found_atstring o null
    Quando ha trovato il suo primo lead, ISO 8601.
L'oggetto account concorrente
{
  "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"
}

Elenca gli account concorrenti

GET/v1/personas/:persona_id/competitor_accountsScope readMCPlist_persona_items

Restituisce gli account concorrenti della buyer persona, ognuno con i suoi lead trovati, valutati e caldi.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un elenco di oggetti account concorrente.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
GET/v1/personas/:persona_id/competitor_accounts
curl \
  https://gemlead.ai/api/v1/personas/lvWBPnytpS/competitor_accounts \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "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
}

Aggiungi account concorrenti

POST/v1/personas/:persona_id/competitor_accountsScope writeMCPedit_persona_items

Aggiunge account concorrenti a una buyer persona. Gemlead legge chi commenta i loro post e ne valuta gli autori.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • usernamesarray di stringsObbligatorio
    Da 1 a 50 account concorrenti da aggiungere, 100 in tutto per buyer persona. Ognuno è uno username X, con o senza la @.

Restituisce

Gli account concorrenti della buyer persona, un elenco di oggetti account concorrente.

Errori

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

Rimuovi account concorrenti

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

Rimuove account concorrenti da una buyer persona. I lead che hanno trovato restano.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri del body

  • usernamesarray di stringsObbligatorio
    Gli account concorrenti da rimuovere, come sono elencati.

Restituisce

Gli account concorrenti rimasti alla buyer persona, un elenco di oggetti account concorrente.

Errori

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

Elenca i lead di un account concorrente

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

Restituisce i lead trovati da un account concorrente, dal punteggio più alto.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Parametri di query

  • usernamestringObbligatorio
    Lo username X del concorrente, come è elencato.
  • orderstring
    -score mette prima i lead migliori, score i più bassi. Di default -score.
    -scorescore
  • limitinteger
    Quanti oggetti restituire, da 1 a 100. Di default 25.
  • cursorstring
    Il next_cursor della pagina precedente, per avere la pagina successiva. Vedi Paginazione.

Restituisce

Un elenco di oggetti lead, con total_count.

Errori

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
Risposta200
{
  "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'oggetto suggerimento di fonte

Un account X che l'IA ha scelto come fonte per una buyer persona, con il motivo e il modo di leggerlo.

Attributi

  • objectstring
    Sempre source_suggestion.
  • profileobject
    Il suo profilo X, come nell'oggetto profilo X.
  • methodstring
    Cosa leggere di questo account.
    followingcompetitor_followers
  • reasonstring o null
    Perché l'IA lo ha scelto.
  • seed_adviceobject o null
    La verifica dell'account fatta da Gemlead.
L'oggetto suggerimento di fonte
{
  "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"
  }
}

Suggerisci fonti

GET/v1/personas/:persona_id/source_suggestionsScope readMCPsuggest_sources

Chiede all'IA account X da aggiungere come fonti, scelti in base a descrizione, parole chiave e concorrenti della buyer persona.

Parametri di percorso

  • persona_idstringObbligatorio
    L'ID della buyer persona.

Restituisce

Un elenco di oggetti suggerimento di fonte.

Errori

  • 404resource_missing
    Nessuna buyer persona con questo ID sull'account della chiave.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra 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"
Risposta200
{
  "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'oggetto profilo X

Un account X letto in tempo reale con la tua sessione X, prima di aggiungerlo come fonte o come concorrente.

Attributi

  • objectstring
    Sempre x_profile.
  • x_user_idstring
    L'ID numerico dell'account X, come stringa.
  • usernamestring
    L'handle X, senza la @.
  • namestring
    Il nome visualizzato.
  • biostring
    La bio del profilo.
  • followers_countinteger
    Follower su X.
  • following_countinteger
    Account che segue su X.
  • locationstring
    La località scritta sul profilo.
  • websitestring
    Il sito web sul profilo.
  • profile_image_urlstring
    L'URL della foto profilo.
  • verifiedboolean
    Se l'account ha il badge di verifica.
  • urlstring
    L'URL del profilo su X.
  • can_dmboolean o null
    Se il tuo account può mandargli un DM, quando X lo indica.
  • joined_atstring o null
    Quando l'account è stato creato su X, ISO 8601.
  • seed_adviceobject
    Solo con il parametro persona. Quanto vale come fonte, una volta per ogni modo di leggerlo.
L'oggetto profilo 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"
}

Consulta un profilo X

GET/v1/x_profiles/:usernameScope readMCPlookup_x_profile

Legge un profilo X in tempo reale con la tua sessione X. Con persona, dice anche quanto vale l'account come fonte per quella buyer persona.

Parametri di percorso

  • usernamestringObbligatorio
    Lo username X, con o senza la @.

Parametri di query

  • personastring
    L'ID di una buyer persona, per avere il relativo seed_advice.

Restituisce

Un oggetto profilo X.

Errori

  • 400x_profile_not_found
    Su X non esiste un profilo leggibile con questo username.
  • 409x_session_expired
    La sessione dell'account X è scaduta. Ricollegalo nell'app, poi riprova.
  • 502upstream_unavailable
    X o un servizio Gemlead non ha risposto. Non è cambiato nulla, riprova tra 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
Risposta200
{
  "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"
    }
  }
}
Ricevi gli aggiornamenti di Gemlead
direttamente nella tua casella email.
Iscriviti
Iscrivendoti accetti la nostra Informativa sulla privacy e acconsenti a ricevere aggiornamenti dalla nostra azienda.
Gemlead
Prodotto
Inizia
Accedi
Per chi
Agenti IA
Funzionalità
Prezzi
Affiliazione
FAQ
Funzionalità
Acquirenti, 24/7Prima i lead caldiOltre il 60% rispondeDM su misuraTutti i DM in un'inboxIl tuo closer IAScala senza limitiAPI, MCP, webhookChiedi a Gemlead
Risorse
HomeAPIBlog
Note legali
Termini
Privacy
© 2026 Gemlead, Inc. Tutti i diritti riservati.
Italiano