API Keys: описание методов

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

Доступ и ключи

• Тариф. API работает на тарифе «Агентство». Если тариф закончился, запросы получают ошибку plan, а ключи остаются и снова заработают после оплаты.
• Ключи создают владелец и администратор пространства на странице «Команда» в разделе «Ключи API». Ключ показывается один раз, сохраните его сразу. До 20 действующих ключей на пространство, отзыв кнопкой «Отозвать» действует мгновенно.
• Права ключа такие же, как у человека, который его создал, и только в проектах этого пространства. Когда человека убирают из команды, его ключи отзываются автоматически.

Подробнее о ключах: Команда: ключи API.

Как отправлять запросы

• Адрес: https://keys.linkodium.com/api/v1/, к нему добавляется путь метода без слэша в конце, например https://keys.linkodium.com/api/v1/projects.
• Ключ передаётся заголовком Authorization: Bearer kk_…. Ключ начинается с kk_, за ним 48 символов.
• Формат: параметры GET-методов передаются в строке запроса, тело POST-методов передаётся в JSON (заголовок Content-Type: application/json, кодировка UTF-8, без сжатия). Тело запроса не больше 40 МБ.
• Ответ всегда JSON. Успешный ответ содержит "ok": true и данные.
• Деньги во всех полях указаны в копейках: balance_kop, price_kop, reserved_kop, cost_kop. 150000 означает 1 500 ₽.
• Время в формате ISO 8601 по UTC, например 2026-10-24T09:12:40Z.

Лимиты

Задания пространства на тарифе «Агентство» стоят в общей очереди сервиса выше остальных.

Ошибки

При ошибке приходит HTTP-статус из таблицы и JSON с полями ok, error (текст на русском, его можно показать человеку) и code (короткий код для программы).

{"ok": false, "error": "Не больше 120 запросов в минуту", "code": "rate_limited"}

Список методов

GET /balance: баланс и тариф

Параметров нет.

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" https://keys.linkodium.com/api/v1/balance

{
  "ok": true,
  "workspace": "Личное пространство",
  "plan": "agency",
  "plan_until": "2026-11-23T10:15:00Z",
  "balance_kop": 1250000,
  "discount": 25
}

GET /regions: номера регионов

Поиск региона по названию для параметров region и regions заданий. Регионы Яндекса и Google нумеруются по-разному, поэтому поисковик указывается явно.

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" "https://keys.linkodium.com/api/v1/regions?engine=google&q=пермь"

{
  "ok": true,
  "engine": "google",
  "regions": [
    {"id": 1011969, "name": "Perm", "path": "Perm, Perm Krai, Russia"}
  ]
}

В задание передавайте id. Если сервис регионов временно недоступен, ответ будет 503 с кодом unavailable.

GET /projects: список проектов

Все проекты пространства, кроме архивных, по порядку создания. Параметров нет.

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" https://keys.linkodium.com/api/v1/projects

{
  "ok": true,
  "projects": [
    {"id": 12, "name": "Стоматология", "site": "example.ru", "phrases": 18450, "updated_at": "2026-10-24T09:12:40Z"}
  ]
}

phrases: число фраз в проекте, updated_at: время последней правки.

POST /projects: создать проект

curl -s -X POST -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"name": "Кальяны", "site": "example.ru"}' https://keys.linkodium.com/api/v1/projects

{"ok": true, "id": 13}

В новом проекте сразу есть группа «Новая группа 1» и формулы KEI по умолчанию.

GET /projects/{id}: проект и группы

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" https://keys.linkodium.com/api/v1/projects/12

{
  "ok": true,
  "project": {
    "id": 12, "name": "Стоматология", "site": "example.ru", "phrases": 18450,
    "kei": [
      {"id": "kei1", "name": "KEI 1 Эффективность (фразовая)", "expr": "((base + phrase) / (base + 0.01) - 1) * 100"}
    ]
  },
  "groups": [
    {"id": 101, "parent_id": null, "name": "Имплантация", "path": "Имплантация", "unused": false},
    {"id": 102, "parent_id": 101, "name": "Цены", "path": "Имплантация / Цены", "unused": false}
  ]
}

• kei: формулы KEI проекта. Значения KEI API не отдаёт: они считаются по формулам из частот и данных выдачи, посчитайте их у себя. Переменные формул описаны в разделе Формулы KEI.
• groups: все группы проекта, отсортированные по пути. parent_id равен null у групп верхнего уровня, path содержит полный путь через « / ». unused равен true у неиспользуемых групп: их фразы не входят в "scope": "all".

GET /projects/{id}/phrases: фразы

Фразы проекта по порядку добавления. Удалённые фразы не возвращаются.

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" "https://keys.linkodium.com/api/v1/projects/12/phrases?limit=1000&offset=0"

{
  "ok": true,
  "phrases": [
    {
      "id": 5501, "text": "имплантация зубов цена", "group_id": 102, "marker": 0, "checked": 0,
      "f_base": 12840, "f_phrase": 3120, "f_exact": 2410, "f_region": 225, "f_period": "year",
      "s_docs": 41000000, "s_main": 2, "s_titles": 7,
      "ya_pos": 4, "ya_prev": 6, "ya_url": "https://example.ru/implant/",
      "g_pos": null, "g_prev": null, "g_url": null,
      "added_at": "2026-10-20T14:03:11Z"
    }
  ],
  "limit": 1000,
  "offset": 0,
  "total": 18450
}

Если данные не собирались, в поле null. total показывает число фраз во всём проекте, даже если задан group_id. Чтобы забрать все фразы, увеличивайте offset на limit, пока не придёт пустой список.

POST /projects/{id}/phrases: добавить фразы

curl -s -X POST -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"group_id": 102, "phrases": ["имплантация зубов цена", "импланты под ключ"]}' \
  https://keys.linkodium.com/api/v1/projects/12/phrases

{"ok": true, "group_id": 102, "added": 1, "existing": 1, "duplicates_in_input": 0}

• added: сколько фраз добавлено. existing: сколько уже было в проекте (в любой группе), они не добавляются и не переносятся. duplicates_in_input: повторы внутри переданного списка.
• Дубли сравниваются без учёта регистра, «ё» и «е» считаются одной буквой. Лишние пробелы убираются, фраза длиннее 400 символов обрезается.
• В колонке «Источник» у таких фраз будет «Файл». Добавление можно отменить в проекте через Ctrl+Z, как обычную правку.
• Если новые фразы не помещаются в лимит тарифа, ничего не добавляется и приходит ошибка invalid.
• Добавление считается правкой проекта от имени владельца ключа. Если в интерфейсе проект правит другой человек, придёт ошибка locked. Право правки запись через API не забирает: люди в интерфейсе продолжают работать как обычно.

POST /projects/{id}/import: загрузить данные фраз

То же, что «Данные → Импорт данных из CSV / Excel» в проекте: данные, снятые в другом месте, записываются в фразы проекта. Бесплатно. Фразы сопоставляются с проектом так же, как при добавлении.

curl -s -X POST -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"phrases": ["имплантация зубов цена", "импланты под ключ"], "values": {"f_base": [12840, 960], "f_exact": [2410, null]}, "new": "skip"}' \
  https://keys.linkodium.com/api/v1/projects/12/import

{
  "ok": true,
  "import": {"rows": 2, "matched": 2, "added": 0, "skipped_new": 0, "updated": 2, "filled": 3, "replaced": 0, "kept": 0, "bad": 0, "dup_input": 0, "empty": 0, "groups_created": 0, "op_id": 8812, "label": "Импорт «API»: данные у 2"},
  "added_ids": [],
  "updated_ids": [5501, 5502]
}

• Числа передавайте числами или строками: «12 840» и «12,5» тоже понимаются. Частота от 0 до 4 294 967 295, главных страниц и заголовков до 255, позиция от 1 до 1000. Позиция 0, прочерк, «>100» или «100+» значит «сайта нет в выдаче». Адрес должен начинаться с http:// или https://.
• bad: сколько значений не удалось понять, они пропущены. kept: сколько значений не записано, потому что у фразы уже было другое значение, а overwrite выключен.
• Импорт можно отменить в проекте через Ctrl+Z: добавленные фразы удалятся, данные фраз вернутся, какими были.
• Если новые фразы не помещаются в лимит тарифа, ничего не меняется и приходит ошибка invalid. Если проект правит другой человек, приходит locked, как при добавлении фраз.

POST /projects/{id}/jobs: цена и запуск задания

Один метод для четырёх видов заданий. Вид задаётся полем kind, остальные поля зависят от вида и повторяют настройки окон меню «Данные».

Сначала узнайте цену

Добавьте к любому заданию "estimate": true: задание не запустится, деньги не зарезервируются, придёт расчёт цены.

curl -s -X POST -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"kind": "freq", "source": "direct", "scope": "all", "estimate": true}' \
  https://keys.linkodium.com/api/v1/projects/12/jobs

{
  "ok": true,
  "estimate": {
    "label": "Частота из Директа: 1520 фраз без частоты",
    "units": {"freq_direct": 1520},
    "price_kop": 1710,
    "full_kop": 1710,
    "discount": 25,
    "exempt": false,
    "balance_kop": 1250000,
    "enough": true
  }
}

Запуск

Тот же запрос без estimate ставит задание в очередь и резервирует price_kop на балансе. По итогу списывается только сделанное, остаток резерва возвращается на баланс. Если денег не хватает, задание не запускается, приходит ошибка invalid.

curl -s -X POST -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"kind": "freq", "source": "direct", "scope": "all"}' \
  https://keys.linkodium.com/api/v1/projects/12/jobs

{"ok": true, "job": 3471, "reserved_kop": 1710}

job: номер задания для GET /jobs/{id}. Задание видно и в проекте, во вкладке «Процессы». Список фраз фиксируется в момент запуска: фразы, добавленные позже, в задание не попадут. Как считается цена: Задания: цена, резерв и списание.

Какие фразы обработать

Для freq, serp и cluster нужен один из параметров:

Регионы задаются номерами регионов Яндекса: 225 Россия, 213 Москва, 2 Санкт-Петербург. По умолчанию везде 225. Найти номер по названию: GET /regions.

collect: сбор фраз по маскам

Фразы для сбора не нужны: задание работает по маскам. Цена: 1 ₽ за маску, подсказки 0,1 ₽ за маску и поисковик, до скидки тарифа.

{"kind": "collect", "masks": "имплантация зубов\nимплант зуба", "region": 213, "elka": true, "suggest_y": true, "group_id": 101, "per_mask": true}

freq: частотность

Цена: прогноз Директа 15 ₽ за 1000 фраз за все три вида сразу, Wordstat 20 ₽ за 1000 фраз за каждый вид, до скидки тарифа.

{"kind": "freq", "source": "direct", "forms": ["base", "phrase", "exact"], "region": 225, "period": "month", "period_num": 0, "scope": "all"}

serp: выдача и позиции

Цена: сразу 2 ₽ за 100 страниц выдачи (страница это 10 результатов), ночью 45 ₽ за 1000 фраз, до скидки тарифа. Сразу резервируется цена полной глубины, а списываются только снятые страницы: сбор останавливается, когда найден сайт.

{"kind": "serp", "mode": "now", "engines": ["yandex"], "regions": {"yandex": 213}, "depth": 30, "device": "desktop", "scope": "all"}

cluster: кластеризация

Нужно минимум две фразы. Цена: по выдаче 25 ₽ за 1000 фраз, с ИИ 90 ₽ за 1000 фраз, по словам бесплатно. Недостающая выдача Яндекса (топ-10, компьютер) снимается сама и входит в цену. Фразы, по которым выдачу получить не удалось, в кластеризации не участвуют и не оплачиваются.

{"kind": "cluster", "method": "ai", "grain": "coarse", "region": 213, "scope": "all"}

Кластеризация через API группы не меняет. Готовые кластеры приходят в result задания, а применить их можно в проекте: окно результата открывается кнопкой «Открыть» во вкладке «Процессы», там же «Создать группы».

GET /jobs/{id}: состояние задания

Возвращает любое задание пространства, в том числе запущенное из интерфейса.

curl -s -H "Authorization: Bearer kk_ВАШ_КЛЮЧ" https://keys.linkodium.com/api/v1/jobs/3471

{
  "ok": true,
  "job": {
    "id": 3471, "kind": "freq", "status": "done",
    "progress": null,
    "result": {"updated": 1520, "nodata": 0},
    "message": "Частота из Директа (за год, регион 225): 1520 фраз",
    "cost_kop": 1710, "reserved_kop": 0,
    "run_after": null, "cancel": false,
    "created_at": "2026-10-24T09:20:05Z", "started_at": "2026-10-24T09:20:06Z", "finished_at": "2026-10-24T09:21:40Z",
    "project_id": 12
  }
}

Что лежит в result

• collect: added добавлено, existing уже были в проекте, minus отсеяно минус-словами, below реже порога, cut не поместилось по тарифу, groups номера групп с фразами.
• freq из Директа: updated фраз с частотой, nodata фраз, по которым Директ не дал данных (за них не списывается). У Wordstat итог только в message.
• serp: итог в message, сами позиции читайте через GET …/phrases.
• cluster: method, noserp номера фраз без выдачи и clusters: список кластеров с полями name (название), center (главная фраза), ids (номера фраз, самые частотные первыми), freq (сумма частот), у ИИ ещё intent.

Как дождаться результата

1. Запустите задание и сохраните номер job.
2. Запрашивайте GET /jobs/{id} раз в 5-10 секунд, пока status не станет done, error или cancelled. Ночные задания ждут ночного окна Яндекса и готовы к утру: для них хватит запроса раз в несколько минут. Пока задание ждёт, оно может снова показывать queued с run_after.
3. После done заберите данные через GET …/phrases или из result.

Чего API не умеет

• отменять задания: это делается во вкладке «Процессы» проекта;
• создавать, переименовывать и удалять группы, кроме создания через group_name;
• удалять, переносить, красить фразы и ставить галочки;
• работать с минус-словами и формулами KEI;
• применять кластеры к группам;
• переносить проекты из KeyCollector, выгружать Excel и файл семядра;
• архивировать и удалять проекты, открывать доступ, управлять командой и оплатой.

Всё это доступно в интерфейсе. Вопросы по API: info@linkodium.com.