Gemlead
Docs
Accedi
Ottieni la tua chiave API

Riferimento API

Campagne

Una campagna porta i lead caldi di una buyer persona attraverso un flusso di passaggi, like, commenti, follow e DM, tutto dal tuo account X, e sposta ogni risposta nella tua inbox. Creane una da un modello o dal tuo flusso, avviala e segui i suoi numeri.

Endpoint

L'oggetto campagna

Un flusso di outreach che invia DM ai lead caldi di una buyer persona, fa follow-up e passa le risposte alla tua inbox.

Attributi

  • idstring
    Identificatore univoco della campagna.
  • objectstring
    Sempre campaign.
  • namestring
    Il nome della campagna.
  • statusstring
    Se la campagna sta inviando.
    draftactivepausedarchived
  • personaobject o null
    La buyer persona i cui lead entrano nella campagna.
  • methodstring o null
    Come sono stati trovati i lead della campagna. Null per le campagne più vecchie.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    I lead con un punteggio più basso non entrano mai nella campagna.
  • daily_limitinteger
    Il numero massimo di nuovi lead che entrano nella campagna ogni giorno, da 5 a 150. Di default 60.
  • statsobject
    Totali dall'avvio della campagna. Una risposta conta se arriva entro 7 giorni dal primo DM.
  • created_atstring
    Quando è stata creata la campagna, ISO 8601.
  • updated_atstring
    Quando la campagna è cambiata l'ultima volta, ISO 8601.
L'oggetto campagna
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Elenca le campagne

GET/v1/campaignsScope readMCPlist_campaigns

Restituisce le tue campagne, dalla più recente.

Parametri di query

  • statusstring
    Solo le campagne con questo stato.
    draftactivepausedarchived
  • personastring
    Solo le campagne della buyer persona con questo ID.
  • 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 campagna.

Errori

  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
GET/v1/campaigns
curl -G https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d status=active
Risposta200
{
  "object": "list",
  "data": [
    {
      "id": "c7RkQ2wLxe",
      "object": "campaign",
      "name": "Tipsters warm intro",
      "status": "active",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "method": "keywords",
      "min_score": 60,
      "daily_limit": 50,
      "stats": {
        "leads": 640,
        "dms_sent": 412,
        "replies": 57,
        "reply_rate": 13.8
      },
      "created_at": "2026-09-14T09:21:05.300Z",
      "updated_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Recupera una campagna

GET/v1/campaigns/:idScope read

Restituisce una campagna.

Parametri di percorso

  • idstringObbligatorio
    L'ID della campagna.

Restituisce

Un oggetto campagna.

Errori

GET/v1/campaigns/:id
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Crea una campagna

POST/v1/campaignsScope writeMCPcreate_campaign

Crea una campagna in bozza. Non parte nulla finché non la avvii. Senza template né flow, la campagna riceve il modello predefinito dell'app, il Flusso di riscaldamento per il B2B e il Flusso istantaneo per il B2C.

Parametri del body

  • persona_idstringObbligatorio
    La buyer persona i cui lead vi entrano.
  • namestringObbligatorio
    Il nome della campagna, fino a 100 caratteri.
  • methodstring
    Entrano solo i lead trovati in questo modo. Omettilo per tutti i lead della buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Entrano solo i lead con almeno questo punteggio, da 0 a 100. Di default 60.
  • daily_limitinteger
    Il numero massimo di nuovi lead che entrano ogni giorno, da 5 a 150. Di default 60. Ogni nuovo lead parte con Radar, che lo aggiunge a una lista X privata dell'account, e oltre qualche centinaio di aggiunte al giorno X le blocca per un periodo da 6 a 24 ore.
  • lead_orderstring
    Quali lead entrano per primi. Di default highest, oppure newest per i metodi basati su parole chiave e concorrenti.
    highestlowestshufflenewest
  • templatestring
    Il flusso da cui partire. Vedi Elenca i modelli di campagna. Non insieme a flow.
    warm_upinstantdirect_messageblank
  • flowobject
    Il tuo flusso, al posto di un modello.

Restituisce

Il nuovo oggetto campagna, con lo status su draft.

Errori

POST/v1/campaigns
curl -X POST https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "persona_id": "lvWBPnytpS",
    "name": "Tipsters warm intro",
    "method": "keywords",
    "daily_limit": 50,
    "template": "instant"
  }'
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "draft",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 0,
    "dms_sent": 0,
    "replies": 0,
    "reply_rate": null
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Avvia una campagna

POST/v1/campaigns/:campaign_id/startScope writeMCPset_campaign_status

Avvia una bozza o riprende una campagna in pausa. I lead entrano e i passaggi partono dal tuo account X.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

L'oggetto campagna, con lo status su active.

Errori

POST/v1/campaigns/:campaign_id/start
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/start \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "active",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Metti in pausa una campagna

POST/v1/campaigns/:campaign_id/pauseScope writeMCPset_campaign_status

Mette in pausa una campagna. Nessun nuovo passaggio parte finché non la riavvii, e i lead mantengono il loro posto.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

L'oggetto campagna, con lo status su paused.

Errori

POST/v1/campaigns/:campaign_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "paused",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Archivia una campagna

POST/v1/campaigns/:campaign_id/archiveScope writeMCPset_campaign_status

Chiude una campagna per sempre. La sua cronologia e le sue conversazioni restano, e Duplica una campagna la fa ripartire.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

L'oggetto campagna, con lo status su archived.

Errori

POST/v1/campaigns/:campaign_id/archive
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/archive \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "name": "Tipsters warm intro",
  "status": "archived",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "created_at": "2026-09-14T09:21:05.300Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Duplica una campagna

POST/v1/campaigns/:campaign_id/duplicateScope writeMCPduplicate_campaign

Copia le impostazioni e il flusso di una campagna, senza i suoi lead, in una nuova bozza.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

Il nuovo oggetto campagna, con lo status su draft.

Errori

POST/v1/campaigns/:campaign_id/duplicate
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/duplicate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c2VbN6mQrz",
  "object": "campaign",
  "name": "Tipsters warm intro copy",
  "status": "draft",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "stats": {
    "leads": 0,
    "dms_sent": 0,
    "replies": 0,
    "reply_rate": null
  },
  "created_at": "2026-11-06T07:45:12.904Z",
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Elimina una campagna

DELETE/v1/campaigns/:campaign_idScope writeMCPdelete_campaign

Elimina una campagna. I suoi lead e le loro conversazioni restano. Non si può annullare.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

Un oggetto con l'id della campagna e deleted impostato su true.

Errori

DELETE/v1/campaigns/:campaign_id
curl -X DELETE \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "deleted": true
}

L'oggetto statistiche della campagna

I risultati di una campagna in un periodo, in totale e giorno per giorno.

Attributi

  • objectstring
    Sempre campaign_stats.
  • campaign_idstring
    L'ID della campagna.
  • fromstring
    Il primo giorno, YYYY-MM-DD.
  • tostring
    L'ultimo giorno, YYYY-MM-DD.
  • totalsobject
    leads_added, dms_sent, replies e reply_rate nel periodo.
  • dailyarray di objects
    Una voce al giorno con date, dms_sent e replies.
L'oggetto statistiche della campagna
{
  "object": "campaign_stats",
  "campaign_id": "c7RkQ2wLxe",
  "from": "2026-10-08",
  "to": "2026-11-06",
  "totals": {
    "leads_added": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "daily": [
    {
      "date": "2026-11-04",
      "dms_sent": 22,
      "replies": 3
    },
    {
      "date": "2026-11-05",
      "dms_sent": 25,
      "replies": 4
    },
    {
      "date": "2026-11-06",
      "dms_sent": 9,
      "replies": 1
    }
  ]
}

Recupera le statistiche della campagna

GET/v1/campaigns/:id/statsScope readMCPget_campaign_stats

Restituisce i risultati di una campagna in un periodo, in totale e giorno per giorno. dms_sent conta i primi DM inviati nel periodo, replies le risposte di quei lead entro 7 giorni. I giorni sono date UTC.

Parametri di percorso

  • idstringObbligatorio
    L'ID della campagna.

Parametri di query

  • fromstring
    Il primo giorno, YYYY-MM-DD. Di default 30 giorni fa.
  • tostring
    L'ultimo giorno, YYYY-MM-DD. Di default oggi.

Restituisce

Un oggetto statistiche della campagna.

Errori

GET/v1/campaigns/:id/stats
curl -G https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/stats \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d from=2026-10-08 \
  -d to=2026-11-06
Risposta200
{
  "object": "campaign_stats",
  "campaign_id": "c7RkQ2wLxe",
  "from": "2026-10-08",
  "to": "2026-11-06",
  "totals": {
    "leads_added": 640,
    "dms_sent": 412,
    "replies": 57,
    "reply_rate": 13.8
  },
  "daily": [
    {
      "date": "2026-11-04",
      "dms_sent": 22,
      "replies": 3
    },
    {
      "date": "2026-11-05",
      "dms_sent": 25,
      "replies": 4
    },
    {
      "date": "2026-11-06",
      "dms_sent": 9,
      "replies": 1
    }
  ]
}

L'oggetto impostazioni della campagna

Le impostazioni di una campagna e il suo flusso completo, ogni passaggio con il suo ID e le sue opzioni.

Attributi

  • objectstring
    Sempre campaign_settings.
  • campaign_idstring
    L'ID della campagna.
  • persona_idstring o null
    La buyer persona i cui lead vi entrano.
  • namestring
    Il nome della campagna.
  • statusstring
    A che punto è la campagna.
    draftactivepausedarchived
  • methodstring o null
    Entrano solo i lead trovati in questo modo. null fa entrare tutti i lead della buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Entrano solo i lead con almeno questo punteggio, da 0 a 100.
  • daily_limitinteger
    Il numero massimo di nuovi lead che entrano ogni giorno, da 5 a 150.
  • lead_orderstring
    Quali lead entrano per primi. highest e lowest per punteggio, shuffle in ordine casuale o newest per i trovati più di recente.
    highestlowestshufflenewest
  • flowobject
    Il suo flusso.
  • updated_atstring
    Quando è cambiata l'ultima volta, ISO 8601.
L'oggetto impostazioni della campagna
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Recupera le impostazioni della campagna

GET/v1/campaigns/:campaign_id/settingsScope readMCPget_campaign_settings

Restituisce le impostazioni di una campagna e il suo flusso, ogni passaggio con il suo ID e le sue opzioni. Leggile prima di modificare il flusso.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Restituisce

Un oggetto impostazioni della campagna.

Errori

GET/v1/campaigns/:campaign_id/settings
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Risposta200
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 60,
  "daily_limit": 50,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

Aggiorna le impostazioni della campagna

PATCH/v1/campaigns/:campaign_id/settingsScope writeMCPupdate_campaign

Modifica le impostazioni che invii e mantiene le altre. Un flow sostituisce l'intero flusso, anche su una campagna attiva. Mantieni gli ID dei passaggi che conservi, così i lead in attesa su di essi restano lì, e l'app sposta gli altri.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Parametri del body

  • namestring
    Il nome della campagna, fino a 100 caratteri.
  • methodstring o null
    Entrano solo i lead trovati in questo modo, null per tutti i lead della buyer persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Entrano solo i lead con almeno questo punteggio, da 0 a 100.
  • daily_limitinteger
    Il numero massimo di nuovi lead che entrano ogni giorno, da 5 a 150.
  • lead_orderstring
    Quali lead entrano per primi. highest e lowest per punteggio, shuffle in ordine casuale o newest per i trovati più di recente.
    highestlowestshufflenewest
  • flowobject
    Il nuovo flusso, completo.

Restituisce

L'oggetto impostazioni della campagna aggiornato.

Errori

PATCH/v1/campaigns/:campaign_id/settings
curl -X PATCH \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "daily_limit": 80,
    "min_score": 70
  }'
Risposta200
{
  "object": "campaign_settings",
  "campaign_id": "c7RkQ2wLxe",
  "persona_id": "lvWBPnytpS",
  "name": "Tipsters warm intro",
  "status": "active",
  "method": "keywords",
  "min_score": 70,
  "daily_limit": 80,
  "lead_order": "newest",
  "flow": {
    "steps": [
      {
        "id": "in-like",
        "type": "like",
        "label": "Like",
        "count": 1
      },
      {
        "id": "in-follow",
        "type": "follow",
        "label": "Follow"
      },
      {
        "id": "in-timer",
        "type": "timer",
        "label": "Timer",
        "duration": "1d"
      },
      {
        "id": "in-inbox",
        "type": "can_dm",
        "label": "Inbox opened test",
        "if_yes": [
          {
            "id": "in-dm",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          },
          {
            "id": "in-comment-bridge",
            "type": "comment",
            "label": "Comment",
            "comment_type": "bridge",
            "language": "auto",
            "instructions": null
          }
        ],
        "if_no": [
          {
            "id": "in-comment-closed",
            "type": "comment",
            "label": "Comment",
            "comment_type": "inbox_closed",
            "language": "auto",
            "instructions": null
          }
        ]
      },
      {
        "id": "in-timer-followup",
        "type": "timer",
        "label": "Timer",
        "duration": "3d"
      },
      {
        "id": "in-dm-followup",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "follow_up",
        "language": "auto",
        "instructions": null,
        "template": null
      },
      {
        "id": "in-cleaner",
        "type": "cleaner",
        "label": "Cleaner",
        "unfollow": true,
        "delete_comments": true,
        "delete_likes": true
      }
    ]
  },
  "updated_at": "2026-11-06T07:45:12.904Z"
}

L'oggetto flusso

I passaggi che una campagna esegue per ogni lead, in ordine. Un bivio esegue if_yes o if_no, poi i passaggi successivi. Un flusso contiene al massimo 60 passaggi, i bivi arrivano a 2 livelli e gli ID dei passaggi sono unici. Un passaggio accetta solo le opzioni del suo tipo. Ogni like, commento, follow e DM parte dal tuo account X. Il canvas nell'app dispone il flusso allo stesso modo dei suoi modelli.

Attributi

  • stepsarray di objectsObbligatorio
    I passaggi, in ordine.
L'oggetto flusso
{
  "steps": [
    {
      "id": "in-like",
      "type": "like",
      "label": "Like",
      "count": 1
    },
    {
      "id": "in-follow",
      "type": "follow",
      "label": "Follow"
    },
    {
      "id": "in-timer",
      "type": "timer",
      "label": "Timer",
      "duration": "1d"
    },
    {
      "id": "in-inbox",
      "type": "can_dm",
      "label": "Inbox opened test",
      "if_yes": [
        {
          "id": "in-dm",
          "type": "send_dm",
          "label": "Direct message",
          "mode": "ai",
          "dm_kind": "cold",
          "language": "auto",
          "instructions": null,
          "template": null
        },
        {
          "id": "in-comment-bridge",
          "type": "comment",
          "label": "Comment",
          "comment_type": "bridge",
          "language": "auto",
          "instructions": null
        }
      ],
      "if_no": [
        {
          "id": "in-comment-closed",
          "type": "comment",
          "label": "Comment",
          "comment_type": "inbox_closed",
          "language": "auto",
          "instructions": null
        }
      ]
    },
    {
      "id": "in-timer-followup",
      "type": "timer",
      "label": "Timer",
      "duration": "3d"
    },
    {
      "id": "in-dm-followup",
      "type": "send_dm",
      "label": "Direct message",
      "mode": "ai",
      "dm_kind": "follow_up",
      "language": "auto",
      "instructions": null,
      "template": null
    },
    {
      "id": "in-cleaner",
      "type": "cleaner",
      "label": "Cleaner",
      "unfollow": true,
      "delete_comments": true,
      "delete_likes": true
    }
  ]
}

L'oggetto lead della campagna

Un lead in una campagna, il passaggio in cui si trova e cosa la campagna ha pubblicato per lui.

Attributi

  • objectstring
    Sempre campaign_lead.
  • idstring o null
    Identificatore univoco del percorso del lead in questa campagna.
  • campaign_idstring
    L'ID della campagna.
  • lead_idstring o null
    L'ID del lead.
  • statusstring
    Lo stato del lead nella campagna, come waiting, replied, completed o failed.
  • stepstring o null
    L'etichetta del passaggio in cui si trova.
  • entered_atstring o null
    Quando è entrato nella campagna, ISO 8601.
  • leadobject o null
    Il lead.
  • postedobject
    Cosa è partito per questo lead.
L'oggetto lead della campagna
{
  "object": "campaign_lead",
  "id": "cl9TzQ4wKa",
  "campaign_id": "c7RkQ2wLxe",
  "lead_id": "msgOtJ8dvT",
  "status": "replied",
  "step": "Direct message",
  "entered_at": "2026-11-05T15:00:08.000Z",
  "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": {}
  },
  "posted": {
    "comments": [],
    "dms": [
      {
        "text": "Hey Jane, saw you want a real checkout for your picks. Want to see how others charge for their Discord?",
        "message_id": "1985300011122233344",
        "at": "2026-11-06T07:58:21.000Z"
      }
    ]
  }
}

Elenca i lead della campagna

GET/v1/campaigns/:campaign_id/leadsScope readMCPlist_campaign_leads

Restituisce i lead di una campagna in base a dove si trovano nel flusso, con quello che la campagna ha pubblicato per ciascuno.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Parametri di query

  • stagestring
    all sono tutti i lead entrati. step quelli che hanno superato il passaggio step_id, fork quelli che hanno preso uno dei suoi rami. dm_sent, replied, finished per i lead completati o con risposta, completed per quelli che hanno finito tutti i passaggi senza rispondere. Di default all.
    allstepforkdm_sentrepliedfinishedcompleted
  • step_idstring
    Con step o fork, l'ID del passaggio.
  • branchstring
    Con fork, il ramo.
    yesno
  • skippedboolean
    Con step su un passaggio di commento o DM, i lead per cui non ha pubblicato nulla.
  • qstring
    Cerca per nome o username.
  • 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 della campagna, con total_count.

Errori

GET/v1/campaigns/:campaign_id/leads
curl -G https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d stage=replied
Risposta200
{
  "object": "list",
  "data": [
    {
      "object": "campaign_lead",
      "id": "cl9TzQ4wKa",
      "campaign_id": "c7RkQ2wLxe",
      "lead_id": "msgOtJ8dvT",
      "status": "replied",
      "step": "Direct message",
      "entered_at": "2026-11-05T15:00:08.000Z",
      "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": {}
      },
      "posted": {
        "comments": [],
        "dms": [
          {
            "text": "Hey Jane, saw you want a real checkout for your picks. Want to see how others charge for their Discord?",
            "message_id": "1985300011122233344",
            "at": "2026-11-06T07:58:21.000Z"
          }
        ]
      }
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0",
  "total_count": 57
}

L'oggetto andamento della campagna

L'attività di una campagna per giorno su 14 giorni o per ora su 24 ore, come nel suo grafico nell'app.

Attributi

  • objectstring
    Sempre campaign_trends.
  • campaign_idstring
    L'ID della campagna.
  • rangestring
    Il periodo.
    14d24h
  • timezonestring
    Il fuso orario degli intervalli.
  • bucketsarray di objects
    Uno per giorno o per ora, ognuno con la sua key e le metriche richieste.
  • totalsobject
    Dall'avvio della campagna, i suoi started, sent, replies e follows, con last_sent_at e last_reply_at.
  • truncatedboolean
    true quando la campagna è troppo grande per contarla per intero.
  • generated_atstring
    Quando sono stati letti i numeri, ISO 8601.
L'oggetto andamento della campagna
{
  "object": "campaign_trends",
  "campaign_id": "c7RkQ2wLxe",
  "range": "14d",
  "timezone": "Europe/Paris",
  "buckets": [
    {
      "key": "2026-11-04",
      "started": 48,
      "sent": 22,
      "replies": 3,
      "follows": 9
    },
    {
      "key": "2026-11-05",
      "started": 50,
      "sent": 25,
      "replies": 4,
      "follows": 11
    },
    {
      "key": "2026-11-06",
      "started": 21,
      "sent": 9,
      "replies": 1,
      "follows": 4
    }
  ],
  "totals": {
    "started": 640,
    "sent": 412,
    "replies": 57,
    "follows": 133,
    "last_sent_at": "2026-11-06T08:20:03.000Z",
    "last_reply_at": "2026-11-06T08:12:44.000Z"
  },
  "truncated": false,
  "generated_at": "2026-11-06T08:30:00.000Z"
}

Recupera l'andamento della campagna

GET/v1/campaigns/:campaign_id/trendsScope readMCPget_campaign_trends

Restituisce i lead avviati, i DM inviati, le risposte e i follow di una campagna per giorno su 14 giorni, o per ora su 24 ore.

Parametri di percorso

  • campaign_idstringObbligatorio
    L'ID della campagna.

Parametri di query

  • metricsstring
    Uno o più tra started, sent, replies e follows, separati da virgole. Di default tutti e quattro.
    startedsentrepliesfollows
  • rangestring
    14d per giorno, 24h per ora. Di default 14d.
    14d24h
  • timezonestring
    Il fuso orario IANA degli intervalli, come Europe/Paris. Di default UTC.

Restituisce

Un oggetto andamento della campagna.

Errori

GET/v1/campaigns/:campaign_id/trends
curl -G \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/trends \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d range=14d \
  --data-urlencode "timezone=Europe/Paris"
Risposta200
{
  "object": "campaign_trends",
  "campaign_id": "c7RkQ2wLxe",
  "range": "14d",
  "timezone": "Europe/Paris",
  "buckets": [
    {
      "key": "2026-11-04",
      "started": 48,
      "sent": 22,
      "replies": 3,
      "follows": 9
    },
    {
      "key": "2026-11-05",
      "started": 50,
      "sent": 25,
      "replies": 4,
      "follows": 11
    },
    {
      "key": "2026-11-06",
      "started": 21,
      "sent": 9,
      "replies": 1,
      "follows": 4
    }
  ],
  "totals": {
    "started": 640,
    "sent": 412,
    "replies": 57,
    "follows": 133,
    "last_sent_at": "2026-11-06T08:20:03.000Z",
    "last_reply_at": "2026-11-06T08:12:44.000Z"
  },
  "truncated": false,
  "generated_at": "2026-11-06T08:30:00.000Z"
}

L'oggetto modello di campagna

Un flusso da cui partire per creare una campagna, come lo propone l'app. Il flusso di ogni modello è un flusso valido per Crea una campagna.

Attributi

  • objectstring
    Sempre campaign_template.
  • idstring
    L'ID del modello, per il parametro template.
    warm_upinstantdirect_messageblank
  • descriptionstring
    Cosa fa il flusso, in poche frasi.
  • defaultboolean
    Se l'app lo sceglie per questo metodo e questo mercato.
  • flowobject
    Il suo flusso.
L'oggetto modello di campagna
{
  "object": "campaign_template",
  "id": "direct_message",
  "description": "Radar waits until they are online, then the message. No warm up.",
  "default": false,
  "flow": {
    "steps": [
      {
        "id": "dm-snapshot",
        "type": "snapshot",
        "label": "Radar"
      },
      {
        "id": "dm-send",
        "type": "send_dm",
        "label": "Direct message",
        "mode": "ai",
        "dm_kind": "cold",
        "language": "auto",
        "instructions": null,
        "template": null
      }
    ]
  }
}

Elenca i modelli di campagna

GET/v1/campaign_templatesScope readMCPlist_campaign_templates

Restituisce i modelli dell'app con i loro flussi completi, il miglior riferimento per ogni tipo di passaggio e ogni opzione. Il Flusso di riscaldamento mette like, commenta e segue prima del DM. Il Flusso istantaneo fa tutto subito e invia il DM un giorno dopo. Il modello Messaggio diretto invia solo il DM.

Parametri di query

  • methodstring
    Il metodo della campagna. Il Flusso istantaneo cambia in base al metodo.
    followingkeywordscompetitor_followerscompetitor_comments
  • marketstring
    Il mercato della buyer persona. In b2c, il modello Messaggio diretto invia subito, senza Radar.
    b2bb2c

Restituisce

Un elenco di oggetti modello di campagna.

Errori

  • 400parameter_invalid
    Un parametro ha un valore che l'API non accetta. param lo indica.
GET/v1/campaign_templates
curl -G https://gemlead.ai/api/v1/campaign_templates \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d method=following \
  -d market=b2b
Risposta200
{
  "object": "list",
  "data": [
    {
      "object": "campaign_template",
      "id": "direct_message",
      "description": "Radar waits until they are online, then the message. No warm up.",
      "default": false,
      "flow": {
        "steps": [
          {
            "id": "dm-snapshot",
            "type": "snapshot",
            "label": "Radar"
          },
          {
            "id": "dm-send",
            "type": "send_dm",
            "label": "Direct message",
            "mode": "ai",
            "dm_kind": "cold",
            "language": "auto",
            "instructions": null,
            "template": null
          }
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
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