Tracking lists

Read a project’s tracking lists through the API: interests, categories, publishers, trends and mention lists, with their items, metrics, roll-ups and matched publications.

Tracking lists are the watchlists you build in the app under TRACKING — interests, categories, publishers, trends and mentions. These endpoints read them back, read-only: the lists a project owns, the items inside each one, the same per-item analytics the tracking pages render, the side-panel roll-ups, and — for mention lists — the publications that matched. Everything is scoped to the project your API key belongs to, and every endpoint here requires the key in the X-API-Key header (or Authorization: Bearer).

#The five kinds

A list has exactly one kind, and the kind decides what an item’s key is. The four item kinds live in one family; mention lists are the fifth and are shaped differently — their items are keywords, and they carry scan state.

entity — a person, organisation, place, event or product. key is the entity UUID, or, for lists built before entity resolution, the plain entity name (both are accepted and returned verbatim).
category — a Google category path, case-sensitive, e.g. /Finance/Investing/Stocks & Bonds.
publisher — a clean domain, lower-case and without www., e.g. example-sport.com.
trend — a trend UUID, the same id used by the Trends API and by https://app.d2tr.com/trend/<id>.
mention — a keyword watchlist. Items are terms: a keyword plus a match type (broad, phrase or exact), so one keyword watched in two modes counts as two terms.

#Scope: markets, window, history

The three analytics endpoints (/metrics, /rollup, /matches) share one scope model, and the resolved scope is echoed back so you can log exactly what you measured.

Shared scope parameters

countrystringoptionaldefault all: ISO 3166-1 alpha-2 (us, de, ru) or all. An explicit country must be one of the key’s markets, otherwise 403. all means “every market this key is entitled to”, and the resolved set comes back in scope.markets.
langstringoptionaldefault all: ISO 639-1 language code (en, ru) or all.
periodstringoptionaldefault 7d: 24h, 7d, 30d, or custom. With custom you must send date_from and date_to.
date_fromstring (ISO-8601)optional: Start of a custom window, UTC. Clamped to your plan’s history — see below.
date_tostring (ISO-8601)optional: End of a custom window, UTC. Defaults to now.
grainstringoptionaldefault day: hour or day. Drives bucket size for time series; hour is only sensible on short windows. Not accepted on /matches.

#List the project’s tracking lists

GET/v1/tracking/listsAPI key

Every list the key’s project owns, newest-updated first, with its item count and the project’s quota usage per kind. This is the index you call first — the list ids feed every other endpoint on this page.

Query parameters

kindstringoptional: Restrict to one kind: entity, category, publisher, trend or mention. Omit for all five. Any other value returns 422.
project_idstring (UUID)optional: Internal keys only. Self-serve keys are already bound to a project and may not override it.
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Page offset, 0 or greater.

curl

curl -s "https://d2tr.com/api/v1/tracking/lists?limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "lists": [
    {
      "id": "7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44",
      "kind": "entity",
      "name": "Competitors",
      "color_index": 2,
      "item_count": 18,
      "created_at": "2026-06-02T09:11:00+00:00",
      "updated_at": "2026-09-10T14:32:00+00:00"
    },
    {
      "id": "c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10",
      "kind": "mention",
      "name": "Brand watch",
      "color_index": 0,
      "item_count": 516,
      "countries": ["RU", "US"],
      "langs": ["RU", "EN"],
      "search_scope": "title",
      "match_types": ["exact", "phrase"],
      "active": true,
      "matches_count": 12843,
      "new_publications_24h": 17,
      "last_scanned_at": "2026-09-12T05:00:11+00:00",
      "next_scan_at": "2026-09-12T06:00:00+00:00",
      "scan_status": "succeeded",
      "scan_error": null,
      "created_at": "2026-05-14T11:02:00+00:00",
      "updated_at": "2026-09-12T05:00:11+00:00"
    }
  ],
  "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
}

#List detail with items

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

One list and everything in it. Items come back newest-added first and are not paginated — lists are small by design (a few dozen items; mention lists cap at 300 keywords / 900 terms).

Path parameters

list_idstring (UUID)required: The list to fetch. Lists of both families resolve through this one route.

curl

curl -s "https://d2tr.com/api/v1/tracking/lists/7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44" \
  -H "X-API-Key: $D2TR_API_KEY"

Response — entity, category, publisher, trend

{
  "id": "7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44",
  "kind": "entity",
  "name": "Competitors",
  "color_index": 2,
  "item_count": 3,
  "created_at": "2026-06-02T09:11:00+00:00",
  "updated_at": "2026-09-10T14:32:00+00:00",
  "items": [
    {
      "key": "c6e08b32-91d4-4f0a-8e77-5b20c1d9a4e3",
      "name": "Politics of South America",
      "type": "topic",
      "added_at": "2026-09-10T14:32:00+00:00"
    },
    {
      "key": "Chuvashia",
      "name": "Chuvashia",
      "type": null,
      "added_at": "2026-07-21T08:04:00+00:00"
    },
    {
      "key": "5f0b9c71-2d3e-4a16-bb88-90c7e2143d55",
      "name": "Example Motors",
      "type": "organization",
      "added_at": "2026-06-02T09:12:00+00:00"
    }
  ]
}

Response — mention

{
  "id": "c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10",
  "kind": "mention",
  "name": "Brand watch",
  "color_index": 0,
  "item_count": 4,
  "countries": ["RU", "US"],
  "langs": ["RU", "EN"],
  "search_scope": "title",
  "active": true,
  "mentions": ["example motors", "example ev"],
  "match_types": ["exact", "phrase"],
  "items": [
    {
      "id": "b2c1e0a9-8f77-4d33-90ab-1c2d3e4f5a60",
      "raw_text": "example motors",
      "match_type": "exact",
      "position": 0,
      "matches_count": 8123,
      "added_at": "2026-05-14T11:02:00+00:00"
    },
    {
      "id": "d4e5f6a7-1b2c-4d3e-8f90-a1b2c3d4e5f6",
      "raw_text": "example motors",
      "match_type": "phrase",
      "position": 1,
      "matches_count": 3390,
      "added_at": "2026-05-14T11:02:00+00:00"
    }
  ],
  "matches_count": 12843,
  "new_publications_24h": 17,
  "extraction_started_at": "2026-05-14T11:02:00+00:00",
  "last_scanned_at": "2026-09-12T05:00:11+00:00",
  "next_scan_at": "2026-09-12T06:00:00+00:00",
  "scan_status": "succeeded",
  "scan_error": null,
  "created_at": "2026-05-14T11:02:00+00:00",
  "updated_at": "2026-09-12T05:00:11+00:00"
}

#List metrics

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

The per-item table you see on a tracking list page: impressions, publications and the movement against the previous window, one row per item, plus a summary for the page you requested. Rows are returned for every requested item — an item with no activity in the window comes back with zeros rather than disappearing, so you can drive a stable table from it.

Path parameters

list_idstring (UUID)required: The list to measure.

Query parameters

countrystringoptionaldefault all: Market, or all for every entitled market. See Scope.
langstringoptionaldefault all: Language filter, or all.
periodstringoptionaldefault 7d: 24h, 7d, 30d or custom.
date_fromstring (ISO-8601)optional: Required with period=custom. Clamped to the plan’s history window.
date_tostring (ISO-8601)optional: Required with period=custom.
grainstringoptionaldefault day: hour or day.
limitintegeroptionaldefault 50: Items per call, 1–200. One call measures exactly one page of items.
offsetintegeroptionaldefault 0: Item offset, 0 or greater. Items are ordered newest-added first.

curl

curl -s "https://d2tr.com/api/v1/tracking/lists/7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44/metrics?country=us&lang=en&period=7d&grain=day&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

#Entity rows

Response

{
  "list_id": "7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44",
  "kind": "entity",
  "scope": {
    "country": "us",
    "markets": ["us"],
    "lang": "en",
    "from": "2026-09-05T00:00:00+00:00",
    "to": "2026-09-12T00:00:00+00:00",
    "grain": "day",
    "prev_from": "2026-08-29T00:00:00+00:00",
    "prev_to": "2026-09-05T00:00:00+00:00",
    "history_days": 30,
    "clamped": false
  },
  "items": [
    {
      "key": "c6e08b32-91d4-4f0a-8e77-5b20c1d9a4e3",
      "name": "Politics of South America",
      "resolved_id": "c6e08b32-91d4-4f0a-8e77-5b20c1d9a4e3",
      "resolved_type": "topic",
      "impressions": 1243500,
      "publications_count": 41,
      "publishers_count": 12,
      "trends_count": 3,
      "avg_position": 3.2,
      "delta_pct": 18.4,
      "rank_delta": 2,
      "lived_hours": 96.5,
      "avg_lifespan_hours": 31.2,
      "impressions_spark": [0, 0, 1200, 8400, 19000, 41000, 88000, 120000, 96000, 74000,
                            51000, 40000, 33000, 28000, 24000, 19000, 15000, 12000,
                            9000, 7000, 5200, 3900, 2400, 1100],
      "publications_spark": [0, 0, 1, 2, 3, 5, 6, 4, 3, 3, 2, 2, 2, 1, 1, 1, 1, 1, 1, 1, 1, 0, 0, 0],
      "related": ["Brazil", "Argentina", "Mercosur"],
      "last_seen": "2026-09-11T18:40:00+00:00"
    },
    {
      "key": "Chuvashia",
      "name": "Chuvashia",
      "resolved_id": null,
      "resolved_type": null,
      "impressions": 0,
      "publications_count": 0,
      "publishers_count": 0,
      "trends_count": 0,
      "avg_position": null,
      "delta_pct": null,
      "rank_delta": null,
      "lived_hours": null,
      "avg_lifespan_hours": null,
      "impressions_spark": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "publications_spark": [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      "related": [],
      "last_seen": null
    }
  ],
  "summary": {
    "scope": "page",
    "impressions": 1243500,
    "publications_count": 41,
    "publishers_count": 12,
    "trends_count": 3,
    "delta_pct": 18.4,
    "impressions_spark": [0, 0, 1200, 8400, 19000, 41000, 88000, 120000, 96000, 74000,
                          51000, 40000, 33000, 28000, 24000, 19000, 15000, 12000,
                          9000, 7000, 5200, 3900, 2400, 1100]
  },
  "total": 18,
  "limit": 2,
  "offset": 0
}

#Category rows

Same envelope; key is the taxonomy path and there is no resolved_type. Related items are sibling categories.

items[] (category)

{
  "key": "/Finance/Investing/Stocks & Bonds",
  "name": "/Finance/Investing/Stocks & Bonds",
  "resolved_id": "/Finance/Investing/Stocks & Bonds",
  "impressions": 884200,
  "publications_count": 233,
  "publishers_count": 54,
  "trends_count": 9,
  "avg_position": 4.1,
  "delta_pct": -6.2,
  "rank_delta": -1,
  "impressions_spark": [ "…24 integers…" ],
  "publications_spark": [ "…24 integers…" ],
  "related": ["/Finance/Investing", "/Finance/Banking"],
  "last_seen": "2026-09-11T21:05:00+00:00"
}

#Publisher rows

key is the domain; requested domains are matched case-insensitively and with or without www.. related carries the publisher’s top entities rather than sibling publishers.

items[] (publisher)

{
  "key": "example-sport.com",
  "name": "Example Sport",
  "resolved_id": "example-sport.com",
  "impressions": 2410900,
  "publications_count": 512,
  "trends_count": 27,
  "avg_position": 2.8,
  "delta_pct": 11.9,
  "rank_delta": 3,
  "impressions_spark": [ "…24 integers…" ],
  "publications_spark": [ "…24 integers…" ],
  "related": ["Premier League", "Example FC"],
  "last_seen": "2026-09-11T23:12:00+00:00"
}

#Trend rows

Trend items add the forecast block the app shows on a tracked trend, and carry the trend’s label and lifecycle state.

items[] (trend)

{
  "key": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "name": "Champions League final",
  "resolved_id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "state": "hot",
  "impressions": 5120400,
  "publications_count": 428,
  "publishers_count": 96,
  "avg_position": 2.4,
  "delta_pct": null,
  "impressions_spark": [ "…24 integers…" ],
  "publications_spark": [ "…24 integers…" ],
  "forecast": {
    "pct_next24h": 12.5,
    "pct_next7d": -38.0,
    "pct_next30d": -71.2,
    "predicted_total_reach": 6100000,
    "predicted_end_at": "2026-09-19T00:00:00+00:00",
    "confidence": 0.62
  },
  "cabinet_url": "https://app.d2tr.com/trend/3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "last_seen": "2026-09-11T19:40:00+00:00"
}

#Mention rows

For a mention list, an “item” is a term, and the row counts the publications it matched inside the window. summary adds a time series at the requested grain.

Response (mention)

{
  "list_id": "c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10",
  "kind": "mention",
  "scope": {
    "country": "all",
    "markets": ["ru", "us"],
    "lang": "all",
    "from": "2026-09-05T00:00:00+00:00",
    "to": "2026-09-12T00:00:00+00:00",
    "grain": "day",
    "prev_from": "2026-08-29T00:00:00+00:00",
    "prev_to": "2026-09-05T00:00:00+00:00",
    "history_days": 30,
    "clamped": false
  },
  "items": [
    {
      "key": "example motors|exact",
      "term_id": "b2c1e0a9-8f77-4d33-90ab-1c2d3e4f5a60",
      "name": "example motors",
      "match_type": "exact",
      "publications_count": 214,
      "impressions": 980400,
      "impressions_spark": [ "…24 integers…" ],
      "last_seen": "2026-09-11T20:15:00+00:00"
    }
  ],
  "summary": {
    "scope": "page",
    "publications_count": 214,
    "impressions": 980400,
    "timeseries": [
      { "ts": "2026-09-05T00:00:00+00:00", "urls": 24, "impressions": 108200 },
      { "ts": "2026-09-06T00:00:00+00:00", "urls": 31, "impressions": 142900 }
    ]
  },
  "total": 4,
  "limit": 50,
  "offset": 0
}

#List roll-up

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

The side panels of a tracking list page, aggregated over the whole list rather than a page of items: who published, which trends the list rode, what it co-occurs with. Not paginated — each block is a short top-N.

Path parameters

list_idstring (UUID)required: The list to aggregate.

Query parameters

countrystringoptionaldefault all: Market, or all. See Scope.
langstringoptionaldefault all: Language filter, or all.
periodstringoptionaldefault 7d: 24h, 7d, 30d or custom.
date_fromstring (ISO-8601)optional: Required with period=custom. Clamped to the plan’s history window.
date_tostring (ISO-8601)optional: Required with period=custom.

curl

curl -s "https://d2tr.com/api/v1/tracking/lists/7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44/rollup?country=all&period=7d" \
  -H "X-API-Key: $D2TR_API_KEY"

Response — entity, category, publisher

{
  "list_id": "7a4f1d90-3c62-4e88-9b01-2ad5f0c91b44",
  "kind": "entity",
  "scope": {
    "country": "all",
    "markets": ["ru", "us"],
    "lang": "all",
    "from": "2026-09-05T00:00:00+00:00",
    "to": "2026-09-12T00:00:00+00:00",
    "prev_from": "2026-08-29T00:00:00+00:00",
    "prev_to": "2026-09-05T00:00:00+00:00",
    "history_days": 30,
    "clamped": false
  },
  "item_count": 18,
  "publishers": [
    { "name": "example-sport.com", "pubs": 84, "imps": 1820400, "delta_pct": 7.1 }
  ],
  "trends": [
    {
      "id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
      "name": "Champions League final",
      "pubs": 31,
      "imps": 640200,
      "delta_pct": 22.8
    }
  ],
  "related": [
    { "name": "Brazil", "entity_id": "1a2b3c4d-5e6f-4071-8293-a4b5c6d7e8f9", "pubs": 12, "imps": 210400 }
  ],
  "groups": [{ "name": "Sports", "pubs": 96, "imps": 2410900 }],
  "types": [{ "name": "organization", "pubs": 58, "imps": 1340200 }]
}

Response — mention facets

{
  "list_id": "c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10",
  "kind": "mention",
  "scope": { "country": "all", "markets": ["ru", "us"], "lang": "all", "from": "…", "to": "…" },
  "publishers": [{ "name": "example-news.ru", "urls": 143 }],
  "entities": [{ "name": "Example Motors", "urls": 96 }],
  "categories": [{ "name": "/Autos & Vehicles", "urls": 88 }]
}

#Mention matches

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

The publications a mention list matched, newest first, with the hits that produced each match. This endpoint exists only for kind=mention; calling it on any other list returns 400 and {"code": "kind_mismatch"}.

Path parameters

list_idstring (UUID)required: A mention list.

Query parameters

countrystringoptionaldefault all: Market, or all. Resolved against both the list’s own countries and the key’s markets — a country the list does not watch yields an empty payload, not an error.
langstringoptionaldefault all: Language filter. A language outside the list’s langs yields an empty payload.
date_fromstring (ISO-8601)optional: Window start, clamped to the plan’s history window. Publications are filtered on when the article was first seen in Discover.
date_tostring (ISO-8601)optional: Window end. Defaults to now.
mentionstring (repeatable)optional: Restrict to one or more keywords, e.g. &mention=example+motors&mention=example+ev.
match_typesstringoptional: Comma-separated subset of broad, phrase, exact.
scopestringoptionaldefault all: Where the hit occurred: all, title, body or both.
qstringoptional: Free-text filter over the matched publications (title and domain).
limitintegeroptionaldefault 200: Number of publications, 1–1000. It bounds publications, not hits.

curl

curl -s "https://d2tr.com/api/v1/tracking/lists/c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10/matches?country=us&lang=en&scope=title&limit=1" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "list_id": "c0d8b512-77ae-41f5-9f2c-0b6e1f33ac10",
  "kind": "mention",
  "scope": {
    "country": "us",
    "markets": ["us"],
    "lang": "en",
    "from": "2026-09-05T00:00:00+00:00",
    "to": "2026-09-12T00:00:00+00:00",
    "history_days": 30,
    "clamped": false
  },
  "publications": [
    {
      "id": "e4db50a5-77a2-4fa0-bdd7-4f2386e671f3",
      "url": "https://www.example-news.com/example-motors-q3",
      "cabinet_url": "https://app.d2tr.com/article/e4db50a5-77a2-4fa0-bdd7-4f2386e671f3",
      "title": "Example Motors beats Q3 delivery estimates",
      "publisher": "Example News",
      "domain": "example-news.com",
      "country": "US",
      "lang": "EN",
      "first_seen_at": "2026-09-11T07:31:00+00:00",
      "article_first_seen_at": "2026-09-11T06:58:00+00:00",
      "snippet": "…Example Motors beats Q3 delivery estimates…"
    }
  ],
  "hits": {
    "e4db50a5-77a2-4fa0-bdd7-4f2386e671f3": {
      "count": 2,
      "mentions": [
        {
          "term_id": "b2c1e0a9-8f77-4d33-90ab-1c2d3e4f5a60",
          "raw_text": "example motors",
          "match_type": "exact",
          "field": "title",
          "matched_text": "Example Motors",
          "snippet": "…Example Motors beats Q3 delivery estimates…"
        }
      ]
    }
  },
  "summary": {
    "matches": 318,
    "publications": 214,
    "mentions": { "example motors": 214, "example ev": 104 }
  },
  "limit": 1
}

#Linking back into the app

Every publication the API returns carries a cabinet_url — the canonical link to that article inside the app, ready to paste into a report, a Slack message or a ticket. It is an additive field: it appears on the mention publications[] above, on the trend roll-up’s top_articles[], and on the existing article payloads of Articles, Trend articles and the Discover feed. Nothing was removed or renamed to make room for it.

You can also build it yourself from the id you already have. Article pages take the URL id — the field is called id on v1 article payloads and url_id on v2 feed payloads, and both are the same identifier:

Build the link

# from a v1 payload:  .articles[].id
# from a v2 payload:  .items[].url_id
# from /matches:      .publications[].id
https://app.d2tr.com/article/<url_id>

# tracked trends (item key of a kind=trend list, or .trends[].id)
https://app.d2tr.com/trend/<trend_id>

curl + jq

curl -s "https://d2tr.com/api/v1/tracking/lists/$LIST/matches?country=us&limit=50" \
  -H "X-API-Key: $D2TR_API_KEY" \
| jq -r '.publications[] | [.article_first_seen_at, .domain, .cabinet_url] | @tsv'

#Errors

The shared status codes and their bodies are documented under Errors & rate limits. These are the ones specific to tracking lists — the machine-readable ones carry an object in detail with a stable code:

403 project_key_required — the key is not bound to a project (an internal or legacy key). Create a key in Project → API Access. Internal keys may instead pass ?project_id=.
403 market_not_entitled — the key is market-scoped but its project has no markets, so country=all resolves to nothing. Add markets in Project → Settings.
403 (region) — an explicit country outside the key’s markets: "API key not authorised for region FR. Allowed: ['RU', 'US']".
404 — {"detail": "tracking list not found"}: unknown id, or a list owned by another project.
400 kind_mismatch — /matches called on a list that is not kind=mention.
422 list_too_large — /rollup on a list with more than 500 items; the body echoes the limit. Plain validation failures (bad kind, limit out of range, period=custom without dates) return the usual 422 list.
503 computing — the aggregate was not in cache and took too long to build. It is being computed in the background: honour Retry-After (about 15 s) and repeat the identical request.

403 project_key_required

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

503 computing

{
  "detail": {
    "code": "computing",
    "message": "Metrics are being computed, retry shortly"
  }
}