APIリファレンス

リード

リードは、GemleadがあなたのペルソナのためにXで見つけた人です。Dana AIが各リードを0から100でスコアリングし、60以上がホットリードになります。フィルターで一覧を取得したり、CRMのIDなど独自のメタデータを付けたり、アプリと同じように個々のリードを操作したりできます。

エンドポイント

GET/v1/leads
GET/v1/leads/:id
PATCH/v1/leads/:id
POST/v1/leads/:lead_id/rescore
POST/v1/leads/:lead_id/refresh
POST/v1/leads/:lead_id/follow
POST/v1/leads/:lead_id/unfollow
POST/v1/leads/:lead_id/convert_to_source
DELETE/v1/leads/:lead_id
GET/v1/leads/:lead_id/origin

リードオブジェクト

GemleadがあなたのペルソナのためにXで見つけた人物。Dana AIが付けたスコアと、アウトリーチの進み具合を含みます。

属性

idstring
リードの一意の識別子。
objectstring
常にleadです。
profileobject
リードのXプロフィール。
scoreintegerまたはnull
リードがペルソナにどれだけ合っているかを、0から100で表します。スコアリングされるまではnullです。
score_reasonstringまたはnull
リードがこのスコアになった理由を、1文か2文で示します。
hotboolean
スコアが60以上の場合はtrue。
statusstring
パイプラインにおけるリードの現在の段階。
pendingscoringscoredin_campaigncontactedin_conversationclosed
personaobjectまたはnull
リードを見つけたペルソナ。
campaignobjectまたはnull
リードが参加しているキャンペーン。該当する場合のみ含まれます。
conversation_idstringまたはnull
リードとの会話。会話が始まると設定されます。会話を取得で使います。
locked_toobjectまたはnull
この人を担当する、オーナーのただ1つのXアカウント。リードは1つのXアカウントにしか割り当てられないため、ほかのアカウントから連絡することはありません。リードがまだどこにも確保されていなければnullです。
found_atstring
Gemleadがリードを見つけた日時。ISO 8601形式です。
scored_atstringまたはnull
リードがスコアリングされた日時。ISO 8601形式です。
updated_atstring
リードが最後に変更された日時。ISO 8601形式です。
metadataobject
リードを更新で設定する、独自のキーと値のペア。

リードオブジェクト

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

リードを一覧表示

GET/v1/leadsreadスコープMCPsearch_leads

リードを返します。デフォルトではスコアリングが新しい順です。フィルターを組み合わせて、必要なリードだけを取得できます。

クエリパラメーター

personastring
このペルソナIDのリードのみ。
statusstring
これらのステータスのリードのみ。scored,in_campaignのようにカンマ区切りで指定します。
pendingscoringscoredin_campaigncontactedin_conversationclosed
score_mininteger
スコアがこの値以上のリードのみ。0から100で指定します。
score_maxinteger
スコアがこの値以下のリードのみ。0から100で指定します。
hotboolean
スコアが60以上のリードはtrue、それ以外はfalseです。
scored_afterstring
この日時より後にスコアリングされたリードのみ。ISO 8601形式です。
scored_beforestring
この日時より前にスコアリングされたリードのみ。ISO 8601形式です。
found_afterstring
この日時より後に見つかったリードのみ。ISO 8601形式です。
found_beforestring
この日時より前に見つかったリードのみ。ISO 8601形式です。
orderstring
並び順。デフォルトは-scored_atで、スコアリングが新しい順です。
-scored_at-score-found_at
limitinteger
返すオブジェクトの数。1から100まで指定でき、デフォルトは25です。
cursorstring
次のページを取得するための、前のページのnext_cursor。ページネーションを参照してください。

戻り値

リードオブジェクトのリスト。

エラー

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

GET/v1/leads

curl -G https://gemlead.ai/api/v1/leads \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -d hot=true \
  -d limit=10

レスポンス200

{
  "object": "list",
  "data": [
    {
      "id": "msgOtJ8dvT",
      "object": "lead",
      "profile": {
        "x_user_id": "1460283925",
        "username": "jane_builds",
        "name": "Jane Doe",
        "bio": "Runs a paid trading community. Daily setups, no hype.",
        "followers_count": 12400,
        "following_count": 380,
        "location": "Austin, TX",
        "website": "https://janedoe.com",
        "profile_image_url": "https://pbs.twimg.com/profile_images/1460283925/jane_400x400.jpg",
        "verified": true,
        "url": "https://x.com/jane_builds"
      },
      "score": 86,
      "score_reason": "Runs a paid trading community and asks how to collect payments for it.",
      "hot": true,
      "status": "scored",
      "persona": {
        "id": "lvWBPnytpS",
        "name": "Tipsters"
      },
      "campaign": null,
      "conversation_id": null,
      "locked_to": null,
      "found_at": "2026-11-05T14:02:11.482Z",
      "scored_at": "2026-11-05T14:03:40.117Z",
      "updated_at": "2026-11-05T14:03:40.117Z",
      "metadata": {}
    }
  ],
  "has_more": true,
  "next_cursor": "eyJzIjoiMjAyNi0xMS0wNVQxNDowMzo0MC4xMTdaIn0"
}

リードを取得

GET/v1/leads/:idreadスコープMCPget_lead

リードを1件返します。

パスパラメーター

idstring必須
リードのID。

戻り値

リードオブジェクト。

エラー

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

GET/v1/leads/:id

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

レスポンス200

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

リードを更新

PATCH/v1/leads/:idwriteスコープMCPupdate_lead

リードに独自のメタデータを設定するか、対応を終えたリードをクローズします。クローズすると、そのリードの未実行のキャンペーンステップが止まり、Gemleadはそれ以上メッセージを送りません。

パスパラメーター

idstring必須
リードのID。

ボディパラメーター

metadataobject
リードのメタデータにマージされるキーと値のペア。キーは英数字、_、-で40文字まで、値は500文字までの文字列で、キーは最大20個です。キーを削除するには値をnullか空文字列にし、すべて消去するにはmetadataをnullにします。
statusstring
closedにすると、リードをクローズします。
closed

戻り値

更新されたリードオブジェクト。

エラー

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

PATCH/v1/leads/:id

curl -X PATCH https://gemlead.ai/api/v1/leads/msgOtJ8dvT \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "metadata": {
      "crm_id": "hs_48213"
    }
  }'

レスポンス200

{
  "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": {
    "crm_id": "hs_48213"
  }
}

リードを再スコアリング

POST/v1/leads/:lead_id/rescorewriteスコープMCPlead_action

ペルソナの説明を変更したあとなどに、Dana AIにペルソナと照らしてリードをもう一度スコアリングさせます。リード1件につき最大2クレジットを使います。1回目の分析で1クレジット、通過すると2回目の分析でさらに1クレジットです。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

リードオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのリードはありません。
502upstream_unavailable
XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

POST/v1/leads/:lead_id/rescore

curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/rescore \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

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

リードを再読み込み

POST/v1/leads/:lead_id/refreshwriteスコープMCPlead_action

リードのXプロフィールを読み直し、新しい自己紹介、写真、フォロワー数を反映します。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

更新されたリードオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのリードはありません。
409x_session_expired
Xアカウントのセッションの有効期限が切れています。アプリで再接続してから、もう一度お試しください。
502upstream_unavailable
XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

POST/v1/leads/:lead_id/refresh

curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/refresh \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

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

リードをフォロー

POST/v1/leads/:lead_id/followwriteスコープMCPlead_action

あなたのXアカウントで、Xのリードをすぐにフォローします。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

リードオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのリードはありません。
400lead_without_x_id
リードにフォローできるXアカウントIDがありません。
409x_session_expired
Xアカウントのセッションの有効期限が切れています。アプリで再接続してから、もう一度お試しください。
502upstream_unavailable
XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

POST/v1/leads/:lead_id/follow

curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/follow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

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

リードのフォローを解除

POST/v1/leads/:lead_id/unfollowwriteスコープMCPlead_action

あなたのXアカウントで、Xのリードのフォローをすぐに解除します。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

リードオブジェクト。

エラー

404resource_missing
キーのアカウントに、このIDのリードはありません。
400lead_without_x_id
リードにフォローを解除できるXアカウントIDがありません。
409x_session_expired
Xアカウントのセッションの有効期限が切れています。アプリで再接続してから、もう一度お試しください。
502upstream_unavailable
XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

POST/v1/leads/:lead_id/unfollow

curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/unfollow \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

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

リードをソースにする

POST/v1/leads/:lead_id/convert_to_sourcewriteスコープMCPconvert_lead_to_source

有望なリードをそのペルソナのソースにして、似た人をさらに見つけます。Gemleadは、そのリードがフォローしているアカウント、フォロワー、またはポストにリプライした人を読み取ります。

パスパラメーター

lead_idstring必須
リードのID。

ボディパラメーター

methodstring
followingはリードがフォローしているアカウント、competitor_followersはフォロワー、competitor_commentsはポストにリプライした人を読み取ります。デフォルトはfollowingです。
followingcompetitor_followerscompetitor_comments

戻り値

lead_id、そのpersona_id、method、新しいソースを含むオブジェクト。competitor_commentsの場合は、ソースの代わりにcompetitor_accountのユーザー名を含みます。

エラー

404resource_missing
キーのアカウントに、このIDのリードはありません。
400lead_not_convertible
リードがどのペルソナにも属していません。
400resource_already_exists
ペルソナには、このアカウントがすでにこの獲得方法のソースとして登録されています。
400limit_reached
ペルソナにはすでに100件の競合アカウントがあります。
400parameter_invalid
APIが受け付けない値のパラメーターがあります。paramにその名前が入ります。
502upstream_unavailable
XまたはGemleadのサービスが応答しませんでした。何も変更されていないので、1分後にもう一度お試しください。

POST/v1/leads/:lead_id/convert_to_source

curl -X POST \
  https://gemlead.ai/api/v1/leads/msgOtJ8dvT/convert_to_source \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "following"
  }'

レスポンス200

{
  "object": "lead_conversion",
  "lead_id": "msgOtJ8dvT",
  "persona_id": "lvWBPnytpS",
  "method": "following",
  "source": {
    "id": "s9KdT3pXwM",
    "object": "source",
    "persona_id": "lvWBPnytpS",
    "method": "following",
    "profile": {
      "username": "pickswithmike",
      "name": "Mike Picks",
      "profile_image_url": "https://pbs.twimg.com/profile_images/1722093311/mike_400x400.jpg",
      "followers_count": 8400,
      "following_count": 1210,
      "url": "https://x.com/pickswithmike"
    },
    "status": "pending",
    "paused": false,
    "error": null,
    "read_following": true,
    "read_followers": false,
    "score_self": true,
    "self_lead_id": "Lp4WqZ7sXe",
    "origin_lead_id": "msgOtJ8dvT",
    "stats": {
      "leads": 1184,
      "scored_leads": 1160,
      "hot_leads": 212,
      "avg_score": 44
    },
    "last_activity_at": "2026-11-05T14:03:40.117Z",
    "last_scraped_at": "2026-11-05T14:02:11.482Z",
    "created_at": "2026-09-14T09:21:05.300Z"
  },
  "competitor_account": null
}

リードを削除

DELETE/v1/leads/:lead_idwriteスコープMCPdelete_lead

リードを削除します。リードは一覧から消え、すべてのキャンペーンで停止します。Gemleadが同じ人物をこのペルソナに再び追加することはありません。すべてのペルソナから除外するには、除外リストに追加してください。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

リードのidと、trueに設定されたdeletedを含むオブジェクト。

エラー

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

DELETE/v1/leads/:lead_id

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

レスポンス200

{
  "id": "msgOtJ8dvT",
  "object": "lead",
  "deleted": true
}

リード発見経路オブジェクト

Gemleadがリードを見つけた経緯、きっかけになったポスト、参加しているすべてのキャンペーン。

属性

objectstring
常にlead_originです。
lead_idstring
リードのID。
personaobjectまたはnull
リードを見つけたペルソナ。
methodstringまたはnull
獲得方法。
followingkeywordscompetitor_followerscompetitor_comments
found_querystringまたはnull
keywordsの場合、リードを見つけたキーワード検索。
source_usernamestringまたはnull
リードを見つけるきっかけになったソースまたは競合アカウント。
found_postobjectまたはnull
リードのきっかけになったポスト。ポスト経由で見つかった場合のみ含まれます。
campaignsobjectsの配列
リードが参加しているキャンペーン。それぞれid、name、そのキャンペーンでのリードのstatus、キャンペーンのmethod、リードの現在のstepを含みます。

リード発見経路オブジェクト

{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}

リードの発見経路を取得

GET/v1/leads/:lead_id/originreadスコープMCPget_lead_origin

Gemleadがリードを見つけた経緯、きっかけになったポスト、参加しているすべてのキャンペーンと現在のステップを返します。

パスパラメーター

lead_idstring必須
リードのID。

戻り値

リード発見経路オブジェクト。

エラー

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

GET/v1/leads/:lead_id/origin

curl https://gemlead.ai/api/v1/leads/msgOtJ8dvT/origin \
  -H "Authorization: Bearer $GEMLEAD_API_KEY"

レスポンス200

{
  "object": "lead_origin",
  "lead_id": "msgOtJ8dvT",
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "method": "keywords",
  "found_query": "paid discord picks",
  "source_username": null,
  "found_post": {
    "method": "keywords",
    "query": "paid discord picks",
    "post_id": "1985102233445566778",
    "text": "Thinking of moving my paid discord picks to a real checkout. Any tips?",
    "url": "https://x.com/i/status/1985102233445566778",
    "posted_at": "2026-11-05T13:40:02.000Z",
    "found_at": "2026-11-05T14:02:11.482Z"
  },
  "campaigns": [
    {
      "id": "c7RkQ2wLxe",
      "name": "Tipsters warm intro",
      "status": "waiting",
      "method": "keywords",
      "step": "Timer"
    }
  ]
}