Справочник 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
Максимум новых лидов, которые попадают в кампанию за сутки, от 5 до 150. По умолчанию 60.
statsobject
Итоги с момента запуска кампании. Ответ засчитывается, если пришёл в течение 7 дней после первого DM.
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/campaignsПраво readMCPlist_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/:idПраво read

Возвращает одну кампанию.

Параметры пути

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/campaignsПраво writeMCPcreate_campaign

Создаёт кампанию как черновик. Ничего не отправляется, пока вы её не запустите. Без template или flow кампания получает сценарий приложения по умолчанию, шаблон «Сценарий прогрева» для B2B и «Мгновенный сценарий» для B2C.

Параметры тела

persona_idstringОбязательно
Персона, лиды которой попадают в кампанию.
namestringОбязательно
Название кампании, до 100 символов.
methodstring
В кампанию попадают только лиды, найденные этим способом. Не указывайте параметр, чтобы взять всех лидов персоны.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
В кампанию попадают только лиды с оценкой не ниже этой, от 0 до 100. По умолчанию 60.
daily_limitinteger
Максимум новых лидов, которые попадают в кампанию за сутки, от 5 до 150. По умолчанию 60. Каждый новый лид начинается с Радара, который добавляет его в приватный список X этого аккаунта, а если таких добавлений больше нескольких сотен в сутки, 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/startПраво writeMCPset_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/pauseПраво writeMCPset_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/archiveПраво writeMCPset_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/duplicateПраво writeMCPduplicate_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_idПраво writeMCPdelete_campaign

Удаляет кампанию. Её лиды и их диалоги остаются. Это действие нельзя отменить.

Параметры пути

campaign_idstringОбязательно
ID кампании.

Возвращает

Объект с id кампании и deleted, равным true.

Ошибки

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 за период.
dailyмассив objects
Одна запись на день с 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/statsПраво readMCPget_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
Максимум новых лидов, которые попадают в кампанию за сутки, от 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/settingsПраво readMCPget_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/settingsПраво writeMCPupdate_campaign

Меняет переданные настройки и сохраняет остальные. flow заменяет весь сценарий, даже у работающей кампании. Сохраняйте ID шагов, которые остаются, и лиды, ждущие на них, останутся на месте, а остальных приложение перенесёт.

Параметры пути

campaign_idstringОбязательно
ID кампании.

Параметры тела

namestring
Название кампании, до 100 символов.
methodstring или null
В кампанию попадают только лиды, найденные этим способом, null для всех лидов персоны.
followingkeywordscompetitor_followerscompetitor_comments
min_scoreinteger
В кампанию попадают только лиды с оценкой не ниже этой, от 0 до 100.
daily_limitinteger
Максимум новых лидов, которые попадают в кампанию за сутки, от 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. Холст в приложении показывает такой сценарий так же, как свои шаблоны.

Атрибуты

stepsмассив objectsОбязательно
Шаги по порядку.

Объект сценария

{
  "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/leadsПраво readMCPlist_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
С step на шаге комментария или DM возвращает лидов, для которых ничего не опубликовано.
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
Часовой пояс интервалов.
bucketsмассив objects
По одной записи на день или на час, каждая со своим 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/trendsПраво readMCPget_campaign_trends

Возвращает взятых в работу лидов, отправленные DM, ответы и подписки кампании по дням за 14 дней или по часам за 24 часа.

Параметры пути

campaign_idstringОбязательно
ID кампании.

Параметры запроса

metricsstring
Любые из started, sent, replies и follows, через запятую. По умолчанию все четыре.
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_templatesПраво readMCPlist_campaign_templates

Возвращает шаблоны приложения с их полными сценариями, лучший образец для каждого типа шага и каждой опции. «Сценарий прогрева» ставит лайки, комментирует и подписывается до DM. «Мгновенный сценарий» делает это сразу и пишет в DM через день. «Личное сообщение» только отправляет DM.

Параметры запроса

methodstring
Метод кампании. От него зависит «Мгновенный сценарий».
followingkeywordscompetitor_followerscompetitor_comments
marketstring
Рынок персоны. В b2c шаблон «Личное сообщение» отправляет сразу, без Радара.
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
}