APIリファレンス

キャンペーン

キャンペーンは、ペルソナのホットリードを、いいね、リプライ、フォロー、DMといった一連のステップに沿って進めます。すべてあなたのXアカウントから行われ、返信はすべて受信トレイに届きます。テンプレートか独自のフローから作成して開始し、数値を追跡できます。

エンドポイント

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

キャンペーンオブジェクト

ペルソナのホットリードにDMを送り、フォローアップを行い、返信を受信トレイに渡すアウトリーチのフロー。

属性

idstring
キャンペーンの一意の識別子。
objectstring
常にcampaignです。
namestring
キャンペーンの名前。
statusstring
キャンペーンが送信中かどうか。
draftactivepausedarchived
personaobjectまたはnull
キャンペーンに入るリードのペルソナ。
methodstringまたはnull
キャンペーンのリードの獲得方法。古いキャンペーンではnullです。
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
スコアがこれより低いリードはキャンペーンに追加されません。
daily_limitinteger
キャンペーンに1日に追加される新規リードの上限。5から150で、デフォルトは60です。
statsobject
キャンペーン開始以降の合計。最初のDMから7日以内に届いた返信がカウントされます。
created_atstring
キャンペーンが作成された日時。ISO 8601形式です。
updated_atstring
キャンペーンが最後に変更された日時。ISO 8601形式です。

キャンペーンオブジェクト

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

キャンペーンを一覧表示

GET/v1/campaignsreadスコープMCPlist_campaigns

キャンペーンを新しい順に返します。

クエリパラメーター

statusstring
このステータスのキャンペーンのみ。
draftactivepausedarchived
personastring
このペルソナIDのキャンペーンのみ。
limitinteger
返すオブジェクトの数。1から100まで指定でき、デフォルトは25です。
cursorstring
次のページを取得するための、前のページのnext_cursor。ページネーションを参照してください。

戻り値

キャンペーンオブジェクトのリスト。

エラー

400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。

GET/v1/campaigns

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

レスポンス200

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

キャンペーンを取得

GET/v1/campaigns/:idreadスコープ

キャンペーンを1件返します。

パスパラメーター

idstring必須
キャンペーンのID。

戻り値

キャンペーンオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。

GET/v1/campaigns/:id

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

レスポンス200

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

キャンペーンを作成

POST/v1/campaignswriteスコープMCPcreate_campaign

キャンペーンを下書きとして作成します。開始するまで何も送信されません。templateもflowも指定しない場合は、アプリのデフォルトが使われます。B2Bはウォームアップフロー、B2Cはインスタントフローです。

ボディパラメーター

persona_idstring必須
キャンペーンに入るリードのペルソナ。
namestring必須
キャンペーンの名前。100文字までです。
methodstring
この獲得方法で見つかったリードのみが追加されます。ペルソナのすべてのリードを対象にするには省略します。
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
スコアがこの値以上のリードのみが追加されます。0から100で、デフォルトは60です。
daily_limitinteger
1日に追加される新規リードの上限。5から150まで指定でき、デフォルトは60です。新しいリードはそれぞれRadarから始まり、Radarはリードをアカウントの非公開のXリストに追加します。1日に数百件を超えると、Xはこの追加を6時間から24時間ブロックします。
lead_orderstring
どのリードから先に追加するか。デフォルトはhighestで、キーワード検索と競合を使う獲得方法ではnewestです。
highestlowestshufflenewest
templatestring
もとにするフロー。キャンペーンテンプレートを一覧表示を参照してください。flowとは併用できません。
warm_upinstantdirect_messageblank
flowobject
テンプレートの代わりに使う、独自のフロー。

戻り値

statusがdraftの、新しいキャンペーンオブジェクト。

エラー

400parameter_missing
必須パラメーターがありません。paramにその名前が入ります。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
400parameter_unknown
ボディに、このエンドポイントが受け付けないフィールドがあります。
404resource_missing
キーのアカウントに、このpersona_idのペルソナはありません。

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

レスポンス200

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

キャンペーンを開始

POST/v1/campaigns/:campaign_id/startwriteスコープMCPset_campaign_status

下書きのキャンペーンを開始するか、一時停止中のキャンペーンを再開します。リードが追加され、あなたのXアカウントからステップが実行されます。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

statusがactiveのキャンペーンオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400campaign_archived
キャンペーンはアーカイブ済みです。再び実行するには複製してください。
400campaign_flow_empty
フローにまだステップがありません。

POST/v1/campaigns/:campaign_id/start

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

レスポンス200

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

キャンペーンを一時停止

POST/v1/campaigns/:campaign_id/pausewriteスコープMCPset_campaign_status

キャンペーンを一時停止します。再び開始するまで新しいステップは実行されず、リードは現在の位置にとどまります。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

statusがpausedのキャンペーンオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400campaign_archived
キャンペーンはアーカイブ済みです。再び実行するには複製してください。
400campaign_not_started
キャンペーンは下書きのため、一時停止する対象がありません。

POST/v1/campaigns/:campaign_id/pause

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

レスポンス200

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

キャンペーンをアーカイブ

POST/v1/campaigns/:campaign_id/archivewriteスコープMCPset_campaign_status

キャンペーンを完全に終了します。履歴と会話は残り、キャンペーンを複製で再び実行できます。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

statusがarchivedのキャンペーンオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。

POST/v1/campaigns/:campaign_id/archive

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

レスポンス200

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

キャンペーンを複製

POST/v1/campaigns/:campaign_id/duplicatewriteスコープMCPduplicate_campaign

キャンペーンの設定とフローを、リードを除いて新しい下書きにコピーします。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

statusがdraftの、新しいキャンペーンオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。

POST/v1/campaigns/:campaign_id/duplicate

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

レスポンス200

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

キャンペーンを削除

DELETE/v1/campaigns/:campaign_idwriteスコープMCPdelete_campaign

キャンペーンを削除します。リードとその会話は残ります。この操作は元に戻せません。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

キャンペーンのidと、trueに設定されたdeletedを含むオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。

DELETE/v1/campaigns/:campaign_id

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

レスポンス200

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

キャンペーン統計オブジェクト

期間内のキャンペーンの成果。合計と日別の値です。

属性

objectstring
常にcampaign_statsです。
campaign_idstring
キャンペーンのID。
fromstring
初日。YYYY-MM-DD形式です。
tostring
最終日。YYYY-MM-DD形式です。
totalsobject
期間内のleads_added、dms_sent、replies、reply_rate。
dailyobjectsの配列
1日につき1件。それぞれdate、dms_sent、repliesを含みます。

キャンペーン統計オブジェクト

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

キャンペーン統計を取得

GET/v1/campaigns/:id/statsreadスコープMCPget_campaign_stats

期間内のキャンペーンの成果を、合計と日別で返します。dms_sentは期間内に送信した初回DMの数、repliesはそのリードから7日以内に届いた返信の数です。日付はUTCです。

パスパラメーター

idstring必須
キャンペーンのID。

クエリパラメーター

fromstring
初日。YYYY-MM-DD形式です。デフォルトは30日前です。
tostring
最終日。YYYY-MM-DD形式です。デフォルトは今日です。

戻り値

キャンペーン統計オブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。

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

レスポンス200

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

キャンペーン設定オブジェクト

キャンペーンの設定とフロー全体。各ステップのIDとオプションを含みます。

属性

objectstring
常にcampaign_settingsです。
campaign_idstring
キャンペーンのID。
persona_idstringまたはnull
キャンペーンに入るリードのペルソナ。
namestring
キャンペーンの名前。
statusstring
キャンペーンの状態。
draftactivepausedarchived
methodstringまたはnull
この獲得方法で見つかったリードのみが追加されます。nullの場合は、ペルソナのすべてのリードが対象です。
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
スコアがこの値以上のリードのみが追加されます。0から100です。
daily_limitinteger
1日に追加される新規リードの上限。5から150です。
lead_orderstring
どのリードから先に追加するか。スコアの高い順のhighest、低い順のlowest、ランダムのshuffle、発見が新しい順のnewestです。
highestlowestshufflenewest
flowobject
キャンペーンのフロー。
updated_atstring
最後に変更された日時。ISO 8601形式です。

キャンペーン設定オブジェクト

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

キャンペーン設定を取得

GET/v1/campaigns/:campaign_id/settingsreadスコープMCPget_campaign_settings

キャンペーンの設定とフローを返します。各ステップのIDとオプションも含みます。フローを編集する前に読み取ってください。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

戻り値

キャンペーン設定オブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。

GET/v1/campaigns/:campaign_id/settings

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

レスポンス200

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

キャンペーン設定を更新

PATCH/v1/campaigns/:campaign_id/settingswriteスコープMCPupdate_campaign

送信した設定だけを変更し、ほかの設定はそのまま残します。flowは、実行中のキャンペーンでもフロー全体を置き換えます。残すステップのIDは変えないでください。そのステップで待機中のリードはそのまま残り、それ以外のリードはアプリが移動します。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

ボディパラメーター

namestring
キャンペーンの名前。100文字までです。
methodstringまたはnull
この獲得方法で見つかったリードのみが追加されます。ペルソナのすべてのリードを対象にするにはnullにします。
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
スコアがこの値以上のリードのみが追加されます。0から100です。
daily_limitinteger
1日に追加される新規リードの上限。5から150です。
lead_orderstring
どのリードから先に追加するか。スコアの高い順のhighest、低い順のlowest、ランダムのshuffle、発見が新しい順のnewestです。
highestlowestshufflenewest
flowobject
新しいフローの全体。

戻り値

更新されたキャンペーン設定オブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
400parameter_unknown
ボディに、このエンドポイントが受け付けないフィールドがあります。
400campaign_archived
アーカイブ済みのキャンペーンのフローを変更しようとしました。代わりに複製してください。

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

レスポンス200

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

キャンペーンが各リードに対して順に実行するステップ。分岐ではif_yesかif_noを実行してから、その後のステップに進みます。フローのステップは最大60個、分岐の入れ子は2階層までで、ステップIDは一意です。各ステップは、そのタイプのオプションのみを受け付けます。いいね、リプライ、フォロー、DMはすべてあなたのXアカウントから送られます。アプリのキャンバスには、アプリのテンプレートと同じレイアウトでフローが表示されます。

属性

stepsobjectsの配列必須
順に並んだステップ。

フローオブジェクト

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

キャンペーンリードオブジェクト

キャンペーン中のリード。現在のステップと、キャンペーンがそのリードに投稿した内容を含みます。

属性

objectstring
常にcampaign_leadです。
idstringまたはnull
このキャンペーンでのリードの進行を表す一意の識別子。
campaign_idstring
キャンペーンのID。
lead_idstringまたはnull
リードのID。
statusstring
キャンペーンでのリードのステータス。waiting、replied、completed、failedなどです。
stepstringまたはnull
現在のステップのラベル。
entered_atstringまたはnull
キャンペーンに追加された日時。ISO 8601形式です。
leadobjectまたはnull
リード。
postedobject
このリードに送られた内容。

キャンペーンリードオブジェクト

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

キャンペーンのリードを一覧表示

GET/v1/campaigns/:campaign_id/leadsreadスコープMCPlist_campaign_leads

キャンペーンのリードを、フロー内の位置ごとに、キャンペーンがそれぞれに投稿した内容とともに返します。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

クエリパラメーター

stagestring
allは追加されたすべてのリード、stepはステップstep_idを通過したリード、forkはその分岐の一方に進んだリードです。dm_sent、repliedのほか、finishedは完了または返信済み、completedは返信なしですべてのステップを終えたリードです。デフォルトはallです。
allstepforkdm_sentrepliedfinishedcompleted
step_idstring
stepまたはforkの場合の、ステップのID。
branchstring
forkの場合の分岐。
yesno
skippedboolean
リプライまたはDMのステップでstepを指定した場合に、何も投稿されなかったリード。
qstring
名前またはユーザー名で検索します。
limitinteger
返すオブジェクトの数。1から100まで指定でき、デフォルトは25です。
cursorstring
次のページを取得するための、前のページのnext_cursor。ページネーションを参照してください。

戻り値

total_count付きの、キャンペーンリードオブジェクトのリスト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。

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

レスポンス200

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

キャンペーン推移オブジェクト

14日間の日別、または24時間の時間別のキャンペーンのアクティビティ。アプリのグラフと同じ内容です。

属性

objectstring
常にcampaign_trendsです。
campaign_idstring
キャンペーンのID。
rangestring
期間。
14d24h
timezonestring
集計単位のタイムゾーン。
bucketsobjectsの配列
1日または1時間ごとに1件。それぞれkeyと、指定した指標を含みます。
totalsobject
キャンペーン開始以降のstarted、sent、replies、followsと、last_sent_at、last_reply_at。
truncatedboolean
キャンペーンが大きすぎて全件を集計できない場合はtrue。
generated_atstring
数値を読み取った日時。ISO 8601形式です。

キャンペーン推移オブジェクト

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

キャンペーンの推移を取得

GET/v1/campaigns/:campaign_id/trendsreadスコープMCPget_campaign_trends

キャンペーンで開始したリード、送信したDM、返信、フォローを、14日間の日別、または24時間の時間別に返します。

パスパラメーター

campaign_idstring必須
キャンペーンのID。

クエリパラメーター

metricsstring
started、sent、replies、followsから、カンマ区切りで任意に指定します。デフォルトは4つすべてです。
startedsentrepliesfollows
rangestring
14dは日別、24hは時間別です。デフォルトは14dです。
14d24h
timezonestring
集計単位のIANAタイムゾーン。Europe/Parisなどです。デフォルトはUTCです。

戻り値

キャンペーン推移オブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのキャンペーンはありません。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。

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"

レスポンス200

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

キャンペーンテンプレートオブジェクト

アプリが提供する、キャンペーンのもとにするフロー。どのテンプレートのフローも、キャンペーンを作成でそのまま使える有効なフローです。

属性

objectstring
常にcampaign_templateです。
idstring
テンプレートのID。templateパラメーターに指定します。
warm_upinstantdirect_messageblank
descriptionstring
フローの内容を数文で説明したもの。
defaultboolean
この獲得方法と市場で、アプリがこのテンプレートを選ぶかどうか。
flowobject
キャンペーンのフロー。

キャンペーンテンプレートオブジェクト

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

キャンペーンテンプレートを一覧表示

GET/v1/campaign_templatesreadスコープMCPlist_campaign_templates

アプリのテンプレートを、フロー全体とともに返します。各ステップタイプとオプションのいちばんの参考になります。ウォームアップフローはDMの前にいいね、リプライ、フォローを行います。インスタントフローはそれをすぐに行い、1日後にDMを送ります。ダイレクトメッセージはDMだけを送ります。

クエリパラメーター

methodstring
キャンペーンの獲得方法。インスタントフローの内容はこれに応じて変わります。
followingkeywordscompetitor_followerscompetitor_comments
marketstring
ペルソナの市場。b2cでは、ダイレクトメッセージはRadarを使わずにすぐ送信します。
b2bb2c

戻り値

キャンペーンテンプレートオブジェクトのリスト。

エラー

400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。

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

レスポンス200

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