Gemlead
Docs
Se connecter
Obtenir ta clé API

Référence API

Campagnes

Une campagne fait passer les leads chauds d'un persona par un parcours d'étapes, likes, commentaires, follows et DM, tous depuis ton compte X, et envoie chaque réponse dans ton inbox. Crée-la à partir d'un modèle ou de ton propre parcours, lance-la et suis ses chiffres.

Endpoints

L'objet campagne

Un parcours de prospection qui envoie des DM aux leads chauds d'un persona, relance et transmet les réponses à ton inbox.

Attributs

  • idstring
    Identifiant unique de la campagne.
  • objectstring
    Toujours campaign.
  • namestring
    Le nom de la campagne.
  • statusstring
    Si la campagne est en train d'envoyer.
    draftactivepausedarchived
  • personaobject ou null
    Le persona dont les leads entrent dans la campagne.
  • methodstring ou null
    Comment les leads de la campagne ont été trouvés. Null pour les anciennes campagnes.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Les leads avec un score plus bas n'entrent jamais dans la campagne.
  • daily_limitinteger
    Le maximum de nouveaux leads qui entrent dans la campagne par jour, de 5 à 150. 60 par défaut.
  • statsobject
    Les totaux depuis le lancement de la campagne. Une réponse compte si elle arrive dans les 7 jours qui suivent le premier DM.
  • created_atstring
    Date de création de la campagne, en ISO 8601.
  • updated_atstring
    Date de la dernière modification de la campagne, en ISO 8601.
L'objet campagne
{
  "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"
}

Lister les campagnes

GET/v1/campaignsScope readMCPlist_campaigns

Renvoie tes campagnes, les plus récentes en premier.

Paramètres de requête

  • statusstring
    Seulement les campagnes avec ce statut.
    draftactivepausedarchived
  • personastring
    Seulement les campagnes du persona avec cet ID.
  • 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 campagne.

Erreurs

  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
GET/v1/campaigns
curl -G https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d status=active
Réponse200
{
  "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
}

Récupérer une campagne

GET/v1/campaigns/:idScope read

Renvoie une campagne.

Paramètres de chemin

  • idstringObligatoire
    L'ID de la campagne.

Renvoie

Un objet campagne.

Erreurs

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

Créer une campagne

POST/v1/campaignsScope writeMCPcreate_campaign

Crée une campagne en brouillon. Rien ne part tant que tu ne l'as pas lancée. Sans template ni flow, la campagne prend le modèle par défaut de l'app, Parcours warm-up en B2B et Parcours instantané en B2C.

Paramètres du corps

  • persona_idstringObligatoire
    Le persona dont les leads y entrent.
  • namestringObligatoire
    Le nom de la campagne, 100 caractères au plus.
  • methodstring
    Seuls les leads trouvés de cette façon entrent. Omets-le pour faire entrer tous les leads du persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Seuls les leads avec au moins ce score entrent, de 0 à 100. 60 par défaut.
  • daily_limitinteger
    Le maximum de nouveaux leads qui entrent par jour, de 5 à 150. 60 par défaut. Chaque nouveau lead commence par le Radar, qui l'ajoute à une liste X privée du compte, et au-delà de quelques centaines par jour, X bloque ces ajouts pendant 6 à 24 heures.
  • lead_orderstring
    Les leads qui entrent en premier. highest par défaut, ou newest pour les méthodes mots-clés et concurrents.
    highestlowestshufflenewest
  • templatestring
    Le parcours de départ. Voir Lister les modèles de campagne. Incompatible avec flow.
    warm_upinstantdirect_messageblank
  • flowobject
    Ton propre parcours, à la place d'un modèle.

Renvoie

Le nouvel objet campagne, avec son status à draft.

Erreurs

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

Lancer une campagne

POST/v1/campaigns/:campaign_id/startScope writeMCPset_campaign_status

Lance un brouillon ou relance une campagne en pause. Les leads entrent et les étapes s'exécutent depuis ton compte X.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

L'objet campagne, avec son status à active.

Erreurs

POST/v1/campaigns/:campaign_id/start
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/start \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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"
}

Mettre une campagne en pause

POST/v1/campaigns/:campaign_id/pauseScope writeMCPset_campaign_status

Met une campagne en pause. Aucune nouvelle étape ne s'exécute tant que tu ne la relances pas, et les leads gardent leur place.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

L'objet campagne, avec son status à paused.

Erreurs

POST/v1/campaigns/:campaign_id/pause
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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"
}

Archiver une campagne

POST/v1/campaigns/:campaign_id/archiveScope writeMCPset_campaign_status

Termine une campagne définitivement. Son historique et ses conversations sont conservés, et Dupliquer une campagne permet de la relancer.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

L'objet campagne, avec son status à archived.

Erreurs

POST/v1/campaigns/:campaign_id/archive
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/archive \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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"
}

Dupliquer une campagne

POST/v1/campaigns/:campaign_id/duplicateScope writeMCPduplicate_campaign

Copie les réglages et le parcours d'une campagne, sans ses leads, dans un nouveau brouillon.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

Le nouvel objet campagne, avec son status à draft.

Erreurs

POST/v1/campaigns/:campaign_id/duplicate
curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/duplicate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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"
}

Supprimer une campagne

DELETE/v1/campaigns/:campaign_idScope writeMCPdelete_campaign

Supprime une campagne. Ses leads et leurs conversations sont conservés. C'est irréversible.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

Un objet avec l'id de la campagne et deleted à true.

Erreurs

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

L'objet stats de campagne

Les résultats d'une campagne sur une période, au total et jour par jour.

Attributs

  • objectstring
    Toujours campaign_stats.
  • campaign_idstring
    L'ID de la campagne.
  • fromstring
    Le premier jour, YYYY-MM-DD.
  • tostring
    Le dernier jour, YYYY-MM-DD.
  • totalsobject
    leads_added, dms_sent, replies et reply_rate sur la période.
  • dailytableau d'objects
    Une entrée par jour avec sa date, ses dms_sent et ses replies.
L'objet stats de campagne
{
  "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
    }
  ]
}

Récupérer les stats d'une campagne

GET/v1/campaigns/:id/statsScope readMCPget_campaign_stats

Renvoie les résultats d'une campagne sur une période, au total et jour par jour. dms_sent compte les premiers DM envoyés sur la période, replies les réponses de ces leads sous 7 jours. Les jours sont des dates UTC.

Paramètres de chemin

  • idstringObligatoire
    L'ID de la campagne.

Paramètres de requête

  • fromstring
    Le premier jour, YYYY-MM-DD. Par défaut il y a 30 jours.
  • tostring
    Le dernier jour, YYYY-MM-DD. Aujourd'hui par défaut.

Renvoie

Un objet stats de campagne.

Erreurs

  • 404resource_missing
    Aucune campagne avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
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
Réponse200
{
  "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'objet réglages de campagne

Les réglages d'une campagne et tout son parcours, chaque étape avec son ID et ses options.

Attributs

  • objectstring
    Toujours campaign_settings.
  • campaign_idstring
    L'ID de la campagne.
  • persona_idstring ou null
    Le persona dont les leads y entrent.
  • namestring
    Le nom de la campagne.
  • statusstring
    Où en est la campagne.
    draftactivepausedarchived
  • methodstring ou null
    Seuls les leads trouvés de cette façon entrent. null laisse entrer tous les leads du persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Seuls les leads avec au moins ce score entrent, de 0 à 100.
  • daily_limitinteger
    Le maximum de nouveaux leads qui entrent par jour, de 5 à 150.
  • lead_orderstring
    Les leads qui entrent en premier. highest pour le meilleur score, lowest pour le plus bas, shuffle au hasard ou newest pour les plus récents.
    highestlowestshufflenewest
  • flowobject
    Son parcours.
  • updated_atstring
    Date de sa dernière modification, en ISO 8601.
L'objet réglages de campagne
{
  "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"
}

Récupérer les réglages d'une campagne

GET/v1/campaigns/:campaign_id/settingsScope readMCPget_campaign_settings

Renvoie les réglages d'une campagne et son parcours, chaque étape avec son ID et ses options. Lis-les avant de modifier le parcours.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Renvoie

Un objet réglages de campagne.

Erreurs

GET/v1/campaigns/:campaign_id/settings
curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"
Réponse200
{
  "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"
}

Modifier les réglages d'une campagne

PATCH/v1/campaigns/:campaign_id/settingsScope writeMCPupdate_campaign

Modifie les réglages que tu envoies et ne touche pas aux autres. Un flow remplace tout le parcours, même sur une campagne en cours. Garde les ID des étapes que tu conserves, les leads qui y attendent restent en place, et l'app déplace les autres.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Paramètres du corps

  • namestring
    Le nom de la campagne, 100 caractères au plus.
  • methodstring ou null
    Seuls les leads trouvés de cette façon entrent, null pour tous les leads du persona.
    followingkeywordscompetitor_followerscompetitor_comments
  • min_scoreinteger
    Seuls les leads avec au moins ce score entrent, de 0 à 100.
  • daily_limitinteger
    Le maximum de nouveaux leads qui entrent par jour, de 5 à 150.
  • lead_orderstring
    Les leads qui entrent en premier. highest pour le meilleur score, lowest pour le plus bas, shuffle au hasard ou newest pour les plus récents.
    highestlowestshufflenewest
  • flowobject
    Le nouveau parcours, en entier.

Renvoie

L'objet réglages de campagne à jour.

Erreurs

  • 404resource_missing
    Aucune campagne avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
  • 400parameter_unknown
    Le corps contient un champ que cet endpoint n'accepte pas.
  • 400campaign_archived
    Tu essaies de modifier le parcours d'une campagne archivée. Duplique-la plutôt.
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
  }'
Réponse200
{
  "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'objet parcours

Les étapes qu'une campagne exécute pour chaque lead, dans l'ordre. Un embranchement exécute if_yes ou if_no, puis les étapes qui le suivent. Un parcours contient 60 étapes au plus, les embranchements s'imbriquent sur 2 niveaux au plus et les ID d'étape sont uniques. Une étape ne prend que les options de son type. Chaque like, commentaire, follow et DM part de ton compte X. Le canvas de l'app affiche le parcours de la même façon que ses propres modèles.

Attributs

  • stepstableau d'objectsObligatoire
    Les étapes, dans l'ordre.
L'objet parcours
{
  "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'objet lead de campagne

Un lead dans une campagne, l'étape où il se trouve et ce que la campagne a publié pour lui.

Attributs

  • objectstring
    Toujours campaign_lead.
  • idstring ou null
    Identifiant unique du passage du lead dans cette campagne.
  • campaign_idstring
    L'ID de la campagne.
  • lead_idstring ou null
    L'ID du lead.
  • statusstring
    Le statut du lead dans la campagne, comme waiting, replied, completed ou failed.
  • stepstring ou null
    Le libellé de l'étape où il se trouve.
  • entered_atstring ou null
    Date d'entrée dans la campagne, en ISO 8601.
  • leadobject ou null
    Le lead.
  • postedobject
    Ce qui a été envoyé à ce lead.
L'objet lead de campagne
{
  "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"
      }
    ]
  }
}

Lister les leads d'une campagne

GET/v1/campaigns/:campaign_id/leadsScope readMCPlist_campaign_leads

Renvoie les leads d'une campagne selon leur avancement dans le parcours, avec ce que la campagne a publié pour chacun.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Paramètres de requête

  • stagestring
    all, tous les leads entrés. step, ceux qui ont passé l'étape step_id, et fork, ceux qui ont pris une de ses branches. dm_sent, replied, finished pour ceux qui ont terminé ou répondu, completed pour ceux qui ont fini toutes les étapes sans répondre. all par défaut.
    allstepforkdm_sentrepliedfinishedcompleted
  • step_idstring
    Avec step ou fork, l'ID de l'étape.
  • branchstring
    Avec fork, la branche.
    yesno
  • skippedboolean
    Avec step sur une étape commentaire ou DM, les leads pour lesquels elle n'a rien publié.
  • qstring
    Recherche par nom ou nom d'utilisateur.
  • 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 de campagne, avec total_count.

Erreurs

  • 404resource_missing
    Aucune campagne avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
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
Réponse200
{
  "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'objet tendances de campagne

L'activité d'une campagne par jour sur 14 jours ou par heure sur 24 heures, comme sur son graphique dans l'app.

Attributs

  • objectstring
    Toujours campaign_trends.
  • campaign_idstring
    L'ID de la campagne.
  • rangestring
    La période.
    14d24h
  • timezonestring
    Le fuseau horaire des tranches.
  • bucketstableau d'objects
    Une tranche par jour ou par heure, chacune avec sa key et les métriques demandées.
  • totalsobject
    Depuis le lancement de la campagne, ses started, sent, replies et follows, avec last_sent_at et last_reply_at.
  • truncatedboolean
    true quand la campagne est trop volumineuse pour être comptée en entier.
  • generated_atstring
    Date du calcul des chiffres, en ISO 8601.
L'objet tendances de campagne
{
  "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"
}

Récupérer les tendances d'une campagne

GET/v1/campaigns/:campaign_id/trendsScope readMCPget_campaign_trends

Renvoie les leads entrés, DM envoyés, réponses et follows d'une campagne, par jour sur 14 jours ou par heure sur 24 heures.

Paramètres de chemin

  • campaign_idstringObligatoire
    L'ID de la campagne.

Paramètres de requête

  • metricsstring
    Une ou plusieurs valeurs parmi started, sent, replies et follows, séparées par des virgules. Les quatre par défaut.
    startedsentrepliesfollows
  • rangestring
    14d par jour, 24h par heure. 14d par défaut.
    14d24h
  • timezonestring
    Le fuseau horaire IANA des tranches, comme Europe/Paris. UTC par défaut.

Renvoie

Un objet tendances de campagne.

Erreurs

  • 404resource_missing
    Aucune campagne avec cet ID sur le compte de la clé.
  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
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"
Réponse200
{
  "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'objet modèle de campagne

Un parcours de départ pour une campagne, tel que l'app le propose. Le parcours de chaque modèle est valide pour Créer une campagne.

Attributs

  • objectstring
    Toujours campaign_template.
  • idstring
    L'ID du modèle, pour le paramètre template.
    warm_upinstantdirect_messageblank
  • descriptionstring
    Ce que fait le parcours, en quelques phrases.
  • defaultboolean
    Si l'app le choisit par défaut pour cette méthode et ce marché.
  • flowobject
    Son parcours.
L'objet modèle de campagne
{
  "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
      }
    ]
  }
}

Lister les modèles de campagne

GET/v1/campaign_templatesScope readMCPlist_campaign_templates

Renvoie les modèles de l'app avec leurs parcours complets, la meilleure référence pour chaque type d'étape et chaque option. Le Parcours warm-up like, commente et suit le lead avant le DM. Le Parcours instantané fait tout ça d'un coup et envoie le DM un jour plus tard. Le modèle DM envoie seulement le DM.

Paramètres de requête

  • methodstring
    La méthode de la campagne. Le Parcours instantané change avec elle.
    followingkeywordscompetitor_followerscompetitor_comments
  • marketstring
    Le marché du persona. En b2c, le modèle DM envoie le message tout de suite, sans Radar.
    b2bb2c

Renvoie

Une liste d'objets modèle de campagne.

Erreurs

  • 400parameter_invalid
    Un paramètre a une valeur que l'API n'accepte pas. param indique lequel.
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
Réponse200
{
  "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
}
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