API-Referenz

Kampagnen

Eine Kampagne führt die heißen Leads einer Persona durch einen Ablauf aus Schritten, Likes, Kommentaren, Follows und DMs, alles von deinem X-Konto aus, und bringt jede Antwort in deinen Posteingang. Erstelle eine aus einer Vorlage oder deinem eigenen Ablauf, starte sie und verfolge ihre Zahlen.

Endpoints

GET/v1/campaigns
GET/v1/campaigns/:id
POST/v1/campaigns
POST/v1/campaigns/:campaign_id/start
POST/v1/campaigns/:campaign_id/pause
POST/v1/campaigns/:campaign_id/archive
POST/v1/campaigns/:campaign_id/duplicate
DELETE/v1/campaigns/:campaign_id
GET/v1/campaigns/:id/stats
GET/v1/campaigns/:campaign_id/settings
PATCH/v1/campaigns/:campaign_id/settings
GET/v1/campaigns/:campaign_id/leads
GET/v1/campaigns/:campaign_id/trends
GET/v1/campaign_templates

Das Kampagnenobjekt

Ein Ablauf zur Kontaktaufnahme, der den heißen Leads einer Persona DMs schickt, nachfasst und die Antworten in deinen Posteingang bringt.

Attribute

idstring
Eindeutige Kennung der Kampagne.
objectstring
Immer campaign.
namestring
Der Name der Kampagne.
statusstring
Ob die Kampagne gerade sendet.
draftactivepausedarchived
personaobject oder null
Die Persona, deren Leads in die Kampagne kommen.
methodstring oder null
Wie die Leads der Kampagne gefunden wurden. Null bei älteren Kampagnen.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
Leads mit einem niedrigeren Score kommen nie in die Kampagne.
daily_limitinteger
Wie viele neue Leads höchstens pro Tag in die Kampagne kommen, 5 bis 150. Standardmäßig 60.
statsobject
Summen seit dem Start der Kampagne. Eine Antwort zählt, wenn sie innerhalb von 7 Tagen nach der ersten DM kommt.
created_atstring
Wann die Kampagne erstellt wurde, ISO 8601.
updated_atstring
Wann sich die Kampagne zuletzt geändert hat, ISO 8601.

Das Kampagnenobjekt

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

Kampagnen auflisten

GET/v1/campaignsScope readMCPlist_campaigns

Gibt deine Kampagnen zurück, die neuesten zuerst.

Query-Parameter

statusstring
Nur Kampagnen mit diesem Status.
draftactivepausedarchived
personastring
Nur Kampagnen dieser Persona-ID.
limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Kampagnenobjekten.

Fehler

400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

GET/v1/campaigns

curl -G https://gemlead.ai/api/v1/campaigns \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d status=active

Antwort200

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

Kampagne abrufen

GET/v1/campaigns/:idScope read

Gibt eine Kampagne zurück.

Pfadparameter

idstringErforderlich
Die ID der Kampagne.

Rückgabe

Ein Kampagnenobjekt.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.

GET/v1/campaigns/:id

curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagne erstellen

POST/v1/campaignsScope writeMCPcreate_campaign

Erstellt eine Kampagne als Entwurf. Es wird nichts gesendet, bis du sie startest. Ohne template oder flow bekommt die Kampagne die Standardvorlage der App, den Aufwärm-Ablauf für B2B und den Sofort-Ablauf für B2C.

Body-Parameter

persona_idstringErforderlich
Die Persona, deren Leads in sie kommen.
namestringErforderlich
Der Name der Kampagne, bis zu 100 Zeichen.
methodstring
Nur Leads, die auf diese Weise gefunden wurden, kommen hinein. Lass den Parameter weg, um alle Leads der Persona aufzunehmen.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
Nur Leads mit mindestens diesem Score kommen hinein, 0 bis 100. Standardmäßig 60.
daily_limitinteger
Wie viele neue Leads höchstens pro Tag hineinkommen, 5 bis 150. Standardmäßig 60. Jeder neue Lead beginnt mit Radar, das ihn zu einer privaten X-Liste des Kontos hinzufügt, und ab einigen Hundert pro Tag blockiert X solche Hinzufügungen für 6 bis 24 Stunden.
lead_orderstring
Welche Leads zuerst hineinkommen. Standardmäßig highest, bei den Methoden Keyword und Konkurrenz newest.
highestlowestshufflenewest
templatestring
Der Ablauf als Ausgangspunkt. Siehe Kampagnenvorlagen auflisten. Nicht zusammen mit flow.
warm_upinstantdirect_messageblank
flowobject
Dein eigener Ablauf statt einer Vorlage.

Rückgabe

Das neue Kampagnenobjekt, mit dem Wert draft in status.

Fehler

400parameter_missing
Ein Pflichtparameter fehlt. param nennt ihn.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.
400parameter_unknown
Der Body enthält ein Feld, das dieser Endpoint nicht akzeptiert.
404resource_missing
Keine Persona mit dieser persona_id im Konto des Schlüssels.

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

Antwort200

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

Kampagne starten

POST/v1/campaigns/:campaign_id/startScope writeMCPset_campaign_status

Startet einen Entwurf oder setzt eine pausierte Kampagne fort. Leads kommen hinein, und die Schritte werden von deinem X-Konto aus ausgeführt.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Das Kampagnenobjekt, mit dem Wert active in status.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400campaign_archived
Die Kampagne ist archiviert. Dupliziere sie, um sie erneut laufen zu lassen.
400campaign_flow_empty
Der Ablauf hat noch keinen Schritt.

POST/v1/campaigns/:campaign_id/start

curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/start \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagne pausieren

POST/v1/campaigns/:campaign_id/pauseScope writeMCPset_campaign_status

Pausiert eine Kampagne. Bis du sie wieder startest, wird kein neuer Schritt ausgeführt, und die Leads behalten ihren Platz.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Das Kampagnenobjekt, mit dem Wert paused in status.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400campaign_archived
Die Kampagne ist archiviert. Dupliziere sie, um sie erneut laufen zu lassen.
400campaign_not_started
Die Kampagne ist ein Entwurf, es gibt nichts zu pausieren.

POST/v1/campaigns/:campaign_id/pause

curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/pause \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagne archivieren

POST/v1/campaigns/:campaign_id/archiveScope writeMCPset_campaign_status

Beendet eine Kampagne endgültig. Ihr Verlauf und ihre Unterhaltungen bleiben erhalten. Mit Kampagne duplizieren lässt du sie erneut laufen.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Das Kampagnenobjekt, mit dem Wert archived in status.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.

POST/v1/campaigns/:campaign_id/archive

curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/archive \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagne duplizieren

POST/v1/campaigns/:campaign_id/duplicateScope writeMCPduplicate_campaign

Kopiert Einstellungen und Ablauf einer Kampagne ohne ihre Leads in einen neuen Entwurf.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Das neue Kampagnenobjekt, mit dem Wert draft in status.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.

POST/v1/campaigns/:campaign_id/duplicate

curl -X POST \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/duplicate \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagne löschen

DELETE/v1/campaigns/:campaign_idScope writeMCPdelete_campaign

Löscht eine Kampagne. Ihre Leads und deren Unterhaltungen bleiben. Das lässt sich nicht rückgängig machen.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Ein Objekt mit der id der Kampagne und dem Wert true in deleted.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.

DELETE/v1/campaigns/:campaign_id

curl -X DELETE \
  https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

{
  "id": "c7RkQ2wLxe",
  "object": "campaign",
  "deleted": true
}

Das Statistikobjekt

Die Ergebnisse einer Kampagne über einen Zeitraum, insgesamt und Tag für Tag.

Attribute

objectstring
Immer campaign_stats.
campaign_idstring
Die ID der Kampagne.
fromstring
Der erste Tag, YYYY-MM-DD.
tostring
Der letzte Tag, YYYY-MM-DD.
totalsobject
leads_added, dms_sent, replies und reply_rate im Zeitraum.
dailyArray von objects
Ein Eintrag pro Tag mit date, dms_sent und replies.

Das Statistikobjekt

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

Kampagnenstatistiken abrufen

GET/v1/campaigns/:id/statsScope readMCPget_campaign_stats

Gibt die Ergebnisse einer Kampagne über einen Zeitraum zurück, insgesamt und Tag für Tag. dms_sent zählt die ersten DMs im Zeitraum, replies die Antworten dieser Leads innerhalb von 7 Tagen. Tage sind UTC-Daten.

Pfadparameter

idstringErforderlich
Die ID der Kampagne.

Query-Parameter

fromstring
Der erste Tag, YYYY-MM-DD. Standardmäßig vor 30 Tagen.
tostring
Der letzte Tag, YYYY-MM-DD. Standardmäßig heute.

Rückgabe

Ein Statistikobjekt.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

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

Antwort200

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

Das Einstellungsobjekt

Die Einstellungen einer Kampagne und ihr ganzer Ablauf, jeder Schritt mit seiner ID und seinen Optionen.

Attribute

objectstring
Immer campaign_settings.
campaign_idstring
Die ID der Kampagne.
persona_idstring oder null
Die Persona, deren Leads in sie kommen.
namestring
Der Name der Kampagne.
statusstring
Der Stand der Kampagne.
draftactivepausedarchived
methodstring oder null
Nur Leads, die auf diese Weise gefunden wurden, kommen hinein. null lässt alle Leads der Persona hinein.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
Nur Leads mit mindestens diesem Score kommen hinein, 0 bis 100.
daily_limitinteger
Höchstzahl neuer Leads pro Tag, 5 bis 150.
lead_orderstring
Welche Leads zuerst hineinkommen. highest nach höchstem Score, lowest, shuffle oder newest nach jüngstem Fund.
highestlowestshufflenewest
flowobject
Ihr Ablauf.
updated_atstring
Letzte Änderung, ISO 8601.

Das Einstellungsobjekt

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

Kampagneneinstellungen abrufen

GET/v1/campaigns/:campaign_id/settingsScope readMCPget_campaign_settings

Gibt die Einstellungen einer Kampagne und ihren Ablauf zurück, jeden Schritt mit seiner ID und seinen Optionen. Lies sie, bevor du den Ablauf bearbeitest.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Rückgabe

Ein Einstellungsobjekt.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.

GET/v1/campaigns/:campaign_id/settings

curl https://gemlead.ai/api/v1/campaigns/c7RkQ2wLxe/settings \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

Antwort200

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

Kampagneneinstellungen ändern

PATCH/v1/campaigns/:campaign_id/settingsScope writeMCPupdate_campaign

Ändert die Einstellungen, die du sendest, und behält die anderen. Ein flow ersetzt den ganzen Ablauf, auch bei einer laufenden Kampagne. Behalte die IDs der Schritte, die bleiben sollen, dann bleiben die Leads dort, die auf ihnen warten, und die App verschiebt die anderen.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Body-Parameter

namestring
Der Name der Kampagne, bis zu 100 Zeichen.
methodstring oder null
Nur Leads, die auf diese Weise gefunden wurden, kommen hinein, null für alle Leads der Persona.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
Nur Leads mit mindestens diesem Score kommen hinein, 0 bis 100.
daily_limitinteger
Höchstzahl neuer Leads pro Tag, 5 bis 150.
lead_orderstring
Welche Leads zuerst hineinkommen. highest nach höchstem Score, lowest, shuffle oder newest nach jüngstem Fund.
highestlowestshufflenewest
flowobject
Der neue Ablauf, vollständig.

Rückgabe

Das aktualisierte Einstellungsobjekt.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.
400parameter_unknown
Der Body enthält ein Feld, das dieser Endpoint nicht akzeptiert.
400campaign_archived
Du hast den Ablauf einer archivierten Kampagne geändert. Dupliziere sie stattdessen.

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
  }'

Antwort200

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

Das Ablaufobjekt

Die Schritte, die eine Kampagne für jeden Lead der Reihe nach ausführt. Eine Verzweigung führt if_yes oder if_no aus, danach die Schritte, die auf sie folgen. Ein Ablauf hat höchstens 60 Schritte, Verzweigungen sind höchstens 2 Ebenen tief verschachtelt, und Schritt-IDs sind eindeutig. Ein Schritt nimmt nur die Optionen seines Typs an. Jedes Like, jeder Kommentar, jedes Follow und jede DM wird von deinem X-Konto aus gesendet. Das Canvas in der App ordnet den Ablauf genauso an wie die Vorlagen der App.

Attribute

stepsArray von objectsErforderlich
Die Schritte, der Reihe nach.

Das Ablaufobjekt

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

Das Kampagnen-Lead-Objekt

Ein Lead in einer Kampagne, der Schritt, auf dem er steht, und was die Kampagne für ihn gepostet hat.

Attribute

objectstring
Immer campaign_lead.
idstring oder null
Eindeutige Kennung des Durchlaufs des Leads in dieser Kampagne.
campaign_idstring
Die ID der Kampagne.
lead_idstring oder null
Die ID des Leads.
statusstring
Der Status des Leads in der Kampagne, etwa waiting, replied, completed oder failed.
stepstring oder null
Die Bezeichnung des Schritts, auf dem er steht.
entered_atstring oder null
Wann er in die Kampagne kam, ISO 8601.
leadobject oder null
Der Lead.
postedobject
Was für diesen Lead gesendet wurde.

Das Kampagnen-Lead-Objekt

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

Kampagnen-Leads auflisten

GET/v1/campaigns/:campaign_id/leadsScope readMCPlist_campaign_leads

Gibt die Leads einer Kampagne nach ihrer Position im Ablauf zurück, mit dem, was die Kampagne für jeden gepostet hat.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Query-Parameter

stagestring
all sind alle Leads, die hineingekommen sind. step sind die, die den Schritt step_id passiert haben, fork die, die einen seiner Zweige genommen haben. dm_sent, replied, finished für abgeschlossen oder geantwortet, completed, wenn alle Schritte ohne Antwort durchlaufen sind. Standardmäßig all.
allstepforkdm_sentrepliedfinishedcompleted
step_idstring
Bei step oder fork die ID des Schritts.
branchstring
Bei fork der Zweig.
yesno
skippedboolean
Bei step auf einem Kommentar- oder DM-Schritt die Leads, für die er nichts gepostet hat.
qstring
Suche nach Name oder Nutzername.
limitinteger
Wie viele Objekte zurückgegeben werden, von 1 bis 100. Standardmäßig 25.
cursorstring
Der next_cursor der vorherigen Seite, um die nächste Seite abzurufen. Siehe Paginierung.

Rückgabe

Eine Liste von Kampagnen-Lead-Objekten, mit total_count.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

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

Antwort200

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

Das Trendobjekt

Die Aktivität einer Kampagne pro Tag über 14 Tage oder pro Stunde über 24 Stunden, wie in ihrem Diagramm in der App.

Attribute

objectstring
Immer campaign_trends.
campaign_idstring
Die ID der Kampagne.
rangestring
Der Zeitraum.
14d24h
timezonestring
Die Zeitzone der Zeitfenster.
bucketsArray von objects
Ein Eintrag pro Tag oder pro Stunde, jeweils mit key und den angefragten Metriken.
totalsobject
Seit dem Start der Kampagne ihre Werte started, sent, replies und follows, mit last_sent_at und last_reply_at.
truncatedboolean
true, wenn die Kampagne zu groß ist, um vollständig gezählt zu werden.
generated_atstring
Wann die Zahlen gelesen wurden, ISO 8601.

Das Trendobjekt

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

Kampagnentrends abrufen

GET/v1/campaigns/:campaign_id/trendsScope readMCPget_campaign_trends

Gibt die gestarteten Leads, gesendeten DMs, Antworten und Follows einer Kampagne zurück, pro Tag über 14 Tage oder pro Stunde über 24 Stunden.

Pfadparameter

campaign_idstringErforderlich
Die ID der Kampagne.

Query-Parameter

metricsstring
Eine Auswahl aus started, sent, replies und follows, durch Kommas getrennt. Standardmäßig alle vier.
startedsentrepliesfollows
rangestring
14d pro Tag, 24h pro Stunde. Standardmäßig 14d.
14d24h
timezonestring
Die IANA-Zeitzone der Zeitfenster, etwa Europe/Paris. Standardmäßig UTC.

Rückgabe

Ein Trendobjekt.

Fehler

404resource_missing
Keine Kampagne mit dieser ID im Konto des Schlüssels.
400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

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"

Antwort200

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

Das Vorlagenobjekt

Ein Ablauf als Ausgangspunkt für eine Kampagne, so wie die App ihn anbietet. Der Ablauf jeder Vorlage ist ein gültiger Ablauf für Kampagne erstellen.

Attribute

objectstring
Immer campaign_template.
idstring
Die ID der Vorlage, für den Parameter template.
warm_upinstantdirect_messageblank
descriptionstring
Was der Ablauf tut, in wenigen Sätzen.
defaultboolean
Ob die App sie für diese Methode und diesen Markt wählt.
flowobject
Ihr Ablauf.

Das Vorlagenobjekt

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

Kampagnenvorlagen auflisten

GET/v1/campaign_templatesScope readMCPlist_campaign_templates

Gibt die Vorlagen der App mit ihren vollständigen Abläufen zurück, die beste Referenz für jeden Schritttyp und jede Option. Der Aufwärm-Ablauf likt, kommentiert und folgt vor der DM. Der Sofort-Ablauf erledigt das alles sofort und schickt die DM einen Tag später. Die Vorlage Direktnachricht sendet nur die DM.

Query-Parameter

methodstring
Die Methode der Kampagne. Der Sofort-Ablauf hängt davon ab.
followingkeywordscompetitor_followerscompetitor_comments
marketstring
Der Markt der Persona. Bei b2c sendet die Vorlage Direktnachricht sofort, ohne Radar.
b2bb2c

Rückgabe

Eine Liste von Vorlagenobjekten.

Fehler

400parameter_invalid
Ein Parameter hat einen Wert, den die API nicht akzeptiert. param nennt ihn.

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

Antwort200

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