Списки отслеживания

Получайте списки отслеживания проекта, их элементы и показатели

Списки отслеживания — это то, что вы собираете в разделе Отслеживание в приложении: интересы, категории, издатели, тренды и упоминания. Методы возвращают сами списки, их элементы и те же показатели, которые вы видите на страницах отслеживания. Методы только читают данные: создавать списки и добавлять элементы можно в приложении.

#Виды списков

Параметр kind повторяет пункты меню Отслеживание. Названия в приложении и значения в API соответствуют друг другу так:

entity — Интересы. В приложении раздел называется «Интересы», в API вид называется entity. Элемент — идентификатор интереса или его название.
category — Категории. Элемент — путь категории, например /Finance/Investing/Stocks & Bonds. Регистр важен.
publisher — Издатели. Элемент — домен в нижнем регистре без www..
trend — Тренды. Элемент — идентификатор тренда.
mention — Упоминания. Элементы — ключевые слова с типом совпадения, а не объекты каталога.

#Списки проекта

GET/v1/tracking/listsAPI key

Возвращает списки проекта, отсортированные по updated_at от новых к старым, и счётчики usage — те же числа, что показывают бейджи меню Отслеживание.

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

kindstringнеобязательный: Оставить списки одного вида: entity, category, publisher, trend или mention. Без параметра возвращаются все виды.
project_idstring (UUID)необязательный: Только для внутренних ключей. Ключ проекта этот параметр игнорирует.
limitintegerнеобязательныйпо умолчанию 50: Размер страницы от 1 до 200.
offsetintegerнеобязательныйпо умолчанию 0: Число пропущенных списков.

curl

curl -s "https://dstrends.com/api/v1/tracking/lists?kind=entity&limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "lists": [
    {
      "id": "6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60",
      "kind": "entity",
      "name": "Финансы",
      "color_index": 2,
      "item_count": 18,
      "created_at": "2026-06-02T09:11:00Z",
      "updated_at": "2026-09-10T18:40:00Z"
    },
    {
      "id": "b7e40a91-2c58-4d66-8f10-77aa31bc0d42",
      "kind": "mention",
      "name": "Бренд",
      "color_index": 0,
      "item_count": 516,
      "countries": ["RU", "US"],
      "langs": ["RU", "EN"],
      "search_scope": "title",
      "active": true,
      "matches_count": 12840,
      "new_publications_24h": 17,
      "last_scanned_at": "2026-09-11T07:00:00Z",
      "scan_status": "succeeded",
      "created_at": "2026-05-14T12:03:00Z",
      "updated_at": "2026-09-11T07:00:00Z"
    }
  ],
  "usage": {
    "entity": { "used": 18, "limit": 1800 },
    "category": { "used": 30, "limit": 1010 },
    "publisher": { "used": 11, "limit": 1010 },
    "trend": { "used": 3, "limit": null },
    "mention": { "used": 516, "limit": 1500 }
  },
  "total": 7,
  "limit": 2,
  "offset": 0
}

usage.<kind>.used считает уникальные элементы вида по всем спискам проекта, а для mention — число ключевых слов с учётом типа совпадения в активных списках. limit берётся из тарифа проекта; у трендов лимита нет, поэтому там null. Поля countries, langs, search_scope, active, matches_count, new_publications_24h, last_scanned_at и scan_status приходят только у списков вида mention.

#Список и его элементы

GET/v1/tracking/lists/{list_id}API key

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

list_idstring (UUID)обязательный: Идентификатор списка.

Элементов в списке немного, поэтому они возвращаются целиком, без постраничной выдачи, в порядке добавления от новых к старым.

curl

curl -s "https://dstrends.com/api/v1/tracking/lists/6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "id": "6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60",
  "kind": "entity",
  "name": "Финансы",
  "color_index": 2,
  "item_count": 18,
  "created_at": "2026-06-02T09:11:00Z",
  "updated_at": "2026-09-10T18:40:00Z",
  "items": [
    {
      "key": "c6e08b32-9a71-4a1d-9c55-0b7de4f21a08",
      "name": "Центральный банк",
      "type": "organization",
      "added_at": "2026-09-10T18:40:00Z"
    },
    {
      "key": "Chuvashia",
      "name": "Chuvashia",
      "type": null,
      "added_at": "2026-08-21T10:02:00Z"
    }
  ]
}

type заполняется только у интересов и может быть null. Список другого проекта или несуществующий идентификатор вернут 404.

#Список упоминаний

Для вида mention тот же метод возвращает ключевые слова, тип совпадения и параметры сканирования:

Ответ

{
  "id": "b7e40a91-2c58-4d66-8f10-77aa31bc0d42",
  "kind": "mention",
  "name": "Бренд",
  "color_index": 0,
  "countries": ["RU", "US"],
  "langs": ["RU", "EN"],
  "search_scope": "title",
  "active": true,
  "mentions": ["дискавер трендс", "discover trends"],
  "match_types": ["exact", "phrase"],
  "items": [
    {
      "key": "8a11c0de-5f22-4f8e-9d31-6b2f0a7c1e44",
      "name": "discover trends",
      "type": "exact",
      "added_at": "2026-05-14T12:03:00Z",
      "position": 0,
      "matches_count": 3120
    }
  ],
  "item_count": 516,
  "matches_count": 12840,
  "new_publications_24h": 17,
  "extraction_started_at": "2026-05-14T12:05:00Z",
  "last_scanned_at": "2026-09-11T07:00:00Z",
  "next_scan_at": "2026-09-11T08:00:00Z",
  "scan_status": "succeeded",
  "scan_error": null,
  "created_at": "2026-05-14T12:03:00Z",
  "updated_at": "2026-09-11T07:00:00Z"
}

У элементов списка упоминаний key — идентификатор ключевого слова, name — его текст, type — тип совпадения (broad, phrase или exact). Одно и то же слово с двумя типами совпадения — два элемента.

#Данные списка

GET/v1/tracking/lists/{list_id}/metricsAPI key

Показатели по элементам списка за выбранный период: те же строки, что в таблице списка в приложении. Один вызов возвращает одну страницу элементов.

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

list_idstring (UUID)обязательный: Идентификатор списка.

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

countrystringнеобязательныйпо умолчанию all: Код страны, например ru или us. Значение all берёт все рынки ключа.
langstringнеобязательныйпо умолчанию all: Код языка. Значение all не ограничивает язык.
periodstringнеобязательныйпо умолчанию 24h: 24h, 7d, 30d или custom. Для custom нужны date_from и date_to.
date_fromstring (ISO 8601)необязательный: Начало периода в UTC, например 2026-09-01T00:00:00Z.
date_tostring (ISO 8601)необязательный: Конец периода в UTC.
grainstringнеобязательныйпо умолчанию day: Шаг спарклайна: hour или day.
limitintegerнеобязательныйпо умолчанию 50: Размер страницы элементов от 1 до 200.
offsetintegerнеобязательныйпо умолчанию 0: Число пропущенных элементов.

curl

curl -s "https://dstrends.com/api/v1/tracking/lists/6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60/metrics?country=ru&period=7d&grain=day&limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "list_id": "6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60",
  "kind": "entity",
  "scope": {
    "country": "ru",
    "markets": ["ru"],
    "lang": "all",
    "from": "2026-09-04T00:00:00Z",
    "to": "2026-09-11T00:00:00Z",
    "grain": "day",
    "prev_from": "2026-08-28T00:00:00Z",
    "prev_to": "2026-09-04T00:00:00Z"
  },
  "items": [
    {
      "key": "c6e08b32-9a71-4a1d-9c55-0b7de4f21a08",
      "name": "Центральный банк",
      "resolved_id": "c6e08b32-9a71-4a1d-9c55-0b7de4f21a08",
      "resolved_type": "organization",
      "impressions": 1284500,
      "publications_count": 41,
      "publishers_count": 12,
      "trends_count": 3,
      "avg_position": 3.2,
      "delta_pct": 18.4,
      "rank_delta": 2,
      "lived_hours": 96,
      "avg_lifespan_hours": 31.5,
      "impressions_spark": [0, 12, 44, 80, 51, 33, 27],
      "publications_spark": [0, 1, 4, 9, 6, 3, 2],
      "related": ["Ключевая ставка", "Инфляция"],
      "last_seen": "2026-09-10T21:15:00Z"
    }
  ],
  "summary": {
    "scope": "page",
    "impressions": 1902300,
    "publications_count": 63,
    "delta_pct": 11.2,
    "impressions_spark": [0, 18, 61, 112, 77, 48, 39]
  },
  "total": 18,
  "limit": 2,
  "offset": 0
}

Спарклайны сжаты до 24 точек — так же, как в приложении. Элемент без данных за период возвращается со значениями 0, а не пропускается: строки всегда совпадают со страницей элементов списка.

summary считается по текущей странице, о чём говорит поле summary.scope со значением page. Сводка по всему списку — в методе /rollup.

#Отличия по видам

category и publisher возвращают тот же набор полей; у издателей вместо related приходит top_entities.
trend добавляет в каждую строку объект forecast с полями pct_next24h, pct_next7d, pct_next30d, predicted_total_reach, predicted_end_at и confidence. Поле delta_pct для трендов равно null.
mention возвращает строки по ключевым словам (name, publications_count, impressions), а в summary.timeseries — массив [{ts, urls, impressions}] с шагом grain.

#Сводка по списку

GET/v1/tracking/lists/{list_id}/rollupAPI key

Агрегаты по всем элементам списка сразу — то, что показывают боковые панели страницы списка: издания, тренды, связанные объекты, группы и типы.

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

list_idstring (UUID)обязательный: Идентификатор списка.

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

countrystringнеобязательныйпо умолчанию all: Код страны или all.
langstringнеобязательныйпо умолчанию all: Код языка или all.
periodstringнеобязательныйпо умолчанию 24h: 24h, 7d, 30d или custom.
date_fromstring (ISO 8601)необязательный: Начало периода для period=custom.
date_tostring (ISO 8601)необязательный: Конец периода для period=custom.

curl

curl -s "https://dstrends.com/api/v1/tracking/lists/6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60/rollup?country=all&period=7d" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "list_id": "6f1d2c33-8a41-4b0e-9f77-1c2d3e4f5a60",
  "kind": "entity",
  "scope": {
    "country": "all",
    "markets": ["ru", "us"],
    "lang": "all",
    "from": "2026-09-04T00:00:00Z",
    "to": "2026-09-11T00:00:00Z"
  },
  "publishers": [
    { "name": "rbc.ru", "pubs": 24, "imps": 640200, "delta_pct": 9.1 }
  ],
  "trends": [
    {
      "id": "20405197-c10b-4a7e-9f03-5d8e1c2b3a44",
      "name": "Заседание ЦБ по ставке",
      "pubs": 12,
      "imps": 310400,
      "delta_pct": 22.7
    }
  ],
  "related": [
    { "name": "Инфляция", "entity_id": "0f2a...", "pubs": 8, "imps": 120300 }
  ],
  "groups": [],
  "types": [{ "name": "organization", "pubs": 31 }]
}

У вида mention метод возвращает срезы publishers, entities и categories, у вида publisher блок publishers пустой, а у вида trend вместо срезов приходит top_articles — публикации трендов списка с полем cabinet_url.

#Совпадения упоминаний

GET/v1/tracking/lists/{list_id}/matchesAPI key

Публикации, в которых нашлись ключевые слова списка. Метод работает только для вида mention; для остальных видов он вернёт 400 с кодом kind_mismatch.

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

list_idstring (UUID)обязательный: Идентификатор списка упоминаний.

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

countrystringнеобязательныйпо умолчанию all: Код страны. Значение all берёт страны списка, разрешённые ключу.
langstringнеобязательныйпо умолчанию all: Код языка. Язык вне списка вернёт пустой результат.
date_fromstring (ISO 8601)необязательный: Начало периода по дате первого показа публикации.
date_tostring (ISO 8601)необязательный: Конец периода.
mentionstringнеобязательный: Ключевое слово. Параметр можно повторять, чтобы оставить несколько слов.
match_typesstringнеобязательный: Типы совпадения через запятую: broad, phrase, exact.
scopestringнеобязательныйпо умолчанию all: Где искать совпадение: title, body, both или all.
qstringнеобязательный: Подстрока в заголовке публикации.
limitintegerнеобязательныйпо умолчанию 200: Число публикаций от 1 до 1000. Ограничение считается по публикациям, а не по совпадениям.

curl

curl -s "https://dstrends.com/api/v1/tracking/lists/b7e40a91-2c58-4d66-8f10-77aa31bc0d42/matches?country=ru&scope=title&limit=2" \
  -H "X-API-Key: $DTR_API_KEY"

Ответ

{
  "list_id": "b7e40a91-2c58-4d66-8f10-77aa31bc0d42",
  "publications": [
    {
      "id": "e4db50a5-77a2-4fa0-bdd7-4f2386e671f3",
      "url": "https://www.example.ru/news/cbr-rate",
      "title": "ЦБ сохранил ставку",
      "publisher": "Пример",
      "domain": "example.ru",
      "country": "RU",
      "lang": "RU",
      "first_seen_at": "2026-09-10T09:12:00Z",
      "article_first_seen_at": "2026-09-10T08:40:00Z",
      "snippet": "…аналитики Discover Trends отметили…",
      "cabinet_url": "https://app.d2tr.com/article/e4db50a5-77a2-4fa0-bdd7-4f2386e671f3"
    }
  ],
  "hits": {
    "e4db50a5-77a2-4fa0-bdd7-4f2386e671f3": {
      "count": 2,
      "mentions": [
        {
          "term_id": "8a11c0de-5f22-4f8e-9d31-6b2f0a7c1e44",
          "raw_text": "discover trends",
          "match_type": "exact",
          "field": "title",
          "matched_text": "Discover Trends"
        }
      ]
    }
  },
  "summary": {
    "matches": 2,
    "publications": 1,
    "mentions": { "discover trends": 2 }
  }
}

#Глубина истории

Период ограничен глубиной истории тарифа проекта — той же, что действует в приложении. На тарифе Start доступны последние 30 дней, на старших тарифах ограничения нет. Слишком ранний date_from не вызывает ошибку: он молча сдвигается, а фактическое окно возвращается в scope.from и scope.to. Сверяйтесь с этими полями, а не с тем, что вы отправили.

#Ссылки в приложение

Публикации в /matches и в top_articles содержат готовую ссылку cabinet_url вида https://app.d2tr.com/article/<id>. Значение собирается из того же идентификатора публикации, который возвращают методы /v1/articles и лента /v2/feed, поэтому его можно построить и самостоятельно.

#Рынки

Явная страна в country проверяется по рынкам ключа: недоступный рынок вернёт 403. Значение all берёт все рынки ключа, и они перечислены в scope.markets — так цифры совпадают с тем, что вы видите в приложении. Ключ, у которого рынков нет, вернёт 403 с кодом market_not_entitled. Подробнее — в разделе «Доступ к рынкам».

#Ошибки

Общие правила описаны в разделе «Ошибки и лимиты». У списков отслеживания есть свои коды в поле detail:

400 kind_mismatch: метод не подходит виду списка, например /matches для списка интересов.
403 project_key_required: ключ не привязан к проекту.
403 market_not_entitled: у ключа нет доступных рынков.
404: список не найден или принадлежит другому проекту.
422 list_too_large: в сводке больше 500 элементов.
429: превышён лимит запросов тарифа.
503 computing: расчёт ещё идёт, повторите запрос через Retry-After секунд.

403 Forbidden

{
  "detail": {
    "code": "project_key_required",
    "message": "Use a project API key (dt_live_…) from Project → API Access"
  }
}