Справочник API

Экспорт

Экспорт собирает в один файл всех лидов, подходящих под ваши фильтры, для выгрузок, слишком больших для постраничного обхода. Создайте экспорт, затем запрашивайте его, пока status не станет ready, и скачайте файл по url. На один аккаунт можно создавать 10 экспортов в час.

Если type равен conversations, файл вместо лидов содержит все диалоги в DM аккаунта, каждый со своим лидом и всеми сообщениями начиная с первого. Такой экспорт нужен, чтобы разом проанализировать ваши DM с помощью ИИ-ассистента или своего кода и увидеть, какое первое сообщение получает ответы, а какой ответ помогает снять возражение лида. Gemlead хранит собственную копию всех DM, синхронизированную с X вместе с правками и удалениями, поэтому файл собирается из этой копии без обращений к X, и 1 500 диалогов готовы меньше чем за минуту.

Эндпоинты

POST/v1/exports
GET/v1/exports
GET/v1/exports/:id

Объект экспорта

Файл с лидами или диалогами, который собирается в фоне, для больших выгрузок, где пагинация слишком медленная.

Атрибуты

idstring
Уникальный идентификатор экспорта.
objectstring
Всегда export.
typestring
Содержимое файла, лиды или диалоги с их сообщениями.
leadsconversations
statusstring
processing, пока файл собирается, затем ready или failed. expired, когда ссылка больше не действует.
processingreadyfailedexpired
formatstring
Формат файла, csv или jsonl для лидов, jsonl или markdown для диалогов.
csvjsonlmarkdown
filtersobject
Фильтры, с которыми создан экспорт, как в запросе Список лидов или Список диалогов.
row_countinteger
Число лидов или диалогов в файле. Оно растёт, пока файл собирается. Не больше 100 000 лидов или 20 000 диалогов.
total_countinteger или null
Для экспорта диалогов без фильтров число диалогов, которые будут в файле, подсчитанное в начале сборки. В остальных случаях null.
urlstring или null
Ссылка на файл, когда он готов. Она действует 24 часа, до expires_at.
expires_atstring или null
Когда url перестанет работать, ISO 8601.
created_atstring
Когда создан экспорт, ISO 8601.

Объект экспорта

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Создание экспорта

POST/v1/exportsПраво readMCPcreate_export

Начинает собирать файл с лидами или диалогами. Сразу отвечает экспортом в статусе processing.

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

typestring
Что экспортировать. По умолчанию leads.
leadsconversations
formatstring
Формат файла. Для лидов csv или jsonl, по умолчанию csv. Для диалогов jsonl или markdown, по умолчанию jsonl.
csvjsonlmarkdown
filtersobject
Лиды для экспорта с фильтрами запроса Список лидов. Для диалогов только persona и unread, как в запросе Список диалогов.

Возвращает

Объект экспорта со статусом processing и HTTP-статусом 202.

Ошибки

400parameter_missing
Отсутствует обязательный параметр. Название параметра указано в param.
400parameter_invalid
API не принимает значение параметра. Название параметра указано в param.
429export_rate_limit_exceeded
Больше 10 экспортов за последний час на этом аккаунте.

POST/v1/exports

curl -X POST https://gemlead.ai/api/v1/exports \
  -H "Authorization: Bearer $GEMLEAD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "format": "csv",
    "filters": {
      "hot": true,
      "persona": "lvWBPnytpS"
    }
  }'

Ответ202

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "processing",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 0,
  "total_count": null,
  "url": null,
  "expires_at": null,
  "created_at": "2026-11-06T07:45:12.904Z"
}

Список экспортов

GET/v1/exportsПраво readMCPlist_exports

Возвращает ваши экспорты, сначала новые.

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

limitinteger
Сколько объектов вернуть, от 1 до 100. По умолчанию 25.
cursorstring
next_cursor предыдущей страницы, чтобы получить следующую. См. раздел Пагинация.

Возвращает

Список объектов экспорта.

GET/v1/exports

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

Ответ200

{
  "object": "list",
  "data": [
    {
      "id": "e4TnW8yHqA",
      "object": "export",
      "type": "leads",
      "status": "ready",
      "format": "csv",
      "filters": {
        "hot": true,
        "persona": "lvWBPnytpS"
      },
      "row_count": 2134,
      "total_count": null,
      "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
      "expires_at": "2026-11-07T07:45:12.904Z",
      "created_at": "2026-11-06T07:45:12.904Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Получение экспорта

GET/v1/exports/:idПраво readMCPget_export

Возвращает экспорт. Запрашивайте его каждые несколько секунд, пока status не станет ready, затем скачайте файл по url.

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

idstringОбязательно
ID экспорта.

Возвращает

Объект экспорта.

Ошибки

404resource_missing
В аккаунте ключа нет экспорта с этим ID.

GET/v1/exports/:id

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

Ответ200

{
  "id": "e4TnW8yHqA",
  "object": "export",
  "type": "leads",
  "status": "ready",
  "format": "csv",
  "filters": {
    "hot": true,
    "persona": "lvWBPnytpS"
  },
  "row_count": 2134,
  "total_count": null,
  "url": "https://parsefiles.back4app.com/7Hn2kQ9xWm4LpR8tV3bZc6YdF1sJ0aUe/5f1c9e2b7a4d8c3e6f0b9a2d1c4e7f8a_gemlead-leads-e4TnW8yHqA.csv",
  "expires_at": "2026-11-07T07:45:12.904Z",
  "created_at": "2026-11-06T07:45:12.904Z"
}

Диалог в файле

Каждая строка файла jsonl с диалогами, сначала самые свежие. Это объект диалога со всей перепиской, лидом и history. Файл markdown содержит то же самое, по одной стенограмме на каждый диалог.

Атрибуты

idstring
Уникальный идентификатор диалога.
objectstring
Всегда conversation.
lead_idstring
Лид, с которым вы общаетесь.
profileobject
Профиль лида в X, как в объекте лида.
personaobject или null
Персона лида.
columnobject или null
Колонка вашей доски диалогов, в которой находится диалог.
unreadboolean
True, если последнее сообщение лида ещё не прочитано.
messages_countinteger
Число сообщений в messages.
first_message_atstring или null
Время первого сообщения, ISO 8601.
last_message_atstring или null
Время последнего сообщения, ISO 8601.
last_messageobject или null
Последнее сообщение.
leadobject или null
Объект лида с его оценкой, статусом, персоной и кампанией.
historystring
complete, если в messages вся переписка. recent, пока Gemlead хранит только последние сообщения длинной переписки, до того как один раз прочитает остальное из X.
completerecent
messagesмассив objects
Все сообщения переписки, сначала старые, с направлением, текстом, временем, медиафайлами и реакциями. Ссылки на медиафайлы действуют 24 часа.

Диалог в файле

{
  "id": "msgOtJ8dvT",
  "object": "conversation",
  "lead_id": "msgOtJ8dvT",
  "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"
  },
  "unread": false,
  "last_message_at": "2026-11-06T08:12:44.000Z",
  "messages_count": 1,
  "last_message": {
    "id": "1985321409876543210",
    "object": "message",
    "direction": "inbound",
    "text": "Yes, I want to charge for my Discord. How does it work?",
    "created_at": "2026-11-06T08:12:44.000Z",
    "media": [],
    "reactions": [],
    "encrypted": false,
    "reply_to_message_id": null
  },
  "persona": {
    "id": "lvWBPnytpS",
    "name": "Tipsters"
  },
  "column": {
    "id": "q7m2xk4p",
    "name": "Interested"
  },
  "first_message_at": "2026-11-06T08:12:44.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": {}
  },
  "history": "complete",
  "messages": [
    {
      "id": "1985321409876543210",
      "object": "message",
      "direction": "inbound",
      "text": "Yes, I want to charge for my Discord. How does it work?",
      "created_at": "2026-11-06T08:12:44.000Z",
      "media": [],
      "reactions": [],
      "encrypted": false,
      "reply_to_message_id": null
    }
  ]
}