Trends

List and inspect trends, their member articles, and the theme → topic → trend hierarchy they belong to.

The Trends endpoints read the live trend graph: individual trends with their lifecycle state, the articles assigned to each, and the parent/child edges of the genealogy DAG. Alongside them, the theme → topic → trend hierarchy exposes global metadata (/v1/themes, /v1/themes/{id}/topics, /v1/topics/{id}/trends) so you can browse trends by subject. Every endpoint here requires an API key sent in the X-API-Key header (or Authorization: Bearer) — there is no ?api_key= query authentication on v1.

#List trends

GET/v1/trendsAPI key

List trends with optional state, structural-type, semantic-type, topic, and theme filters, sorted and paginated. total is the exact filtered count, so you can page with limit/offset.

Query parameters

statestringoptional: Lifecycle filter: emerging, hot, persistent, seasonal_dormant, or decayed.
structural_typestringoptional: Structural filter: event_driven, evergreen, cyclic, derivative, or unknown.
semantic_typestringoptional: Semantic taxonomy filter: news, event_based, seasonal, lifestyle, evergreen, or unclassified (returns trends with no semantic type yet).
topic_idstring (UUID)optional: Restrict to a single topic (a level-1 node).
theme_idstring (UUID)optional: Restrict to all topics under a theme (a level-2 node). If the theme has no topics, returns an empty list.
min_articlesintegeroptionaldefault 1: Only trends with article_count at or above this value (range 0–100000); 0 disables the filter.
sort_bystringoptionaldefault last_article_at: Sort column: last_article_at, first_seen_at, or article_count.
sort_orderstringoptionaldefault desc: asc or desc. Nulls sort last.
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Page offset, 0 or greater.

curl

curl -s "https://d2tr.com/api/v1/trends?state=hot&structural_type=event_driven&min_articles=5&sort_by=article_count&sort_order=desc&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "trends": [
    {
      "id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
      "label": "Champions League final",
      "summary": "Coverage of the UEFA Champions League final and build-up.",
      "label_en": "Champions League final",
      "label_ru": "Финал Лиги чемпионов",
      "label_local": null,
      "label_local_lang": null,
      "state": "hot",
      "structural_type": "event_driven",
      "semantic_type": "event_based",
      "semantic_type_confidence": 0.91,
      "article_count": 428,
      "first_seen_at": "2026-05-20T08:14:00+00:00",
      "last_article_at": "2026-05-31T21:07:00+00:00",
      "peak_date": "2026-05-31",
      "expected_next_peak": null,
      "key_entities": ["UEFA", "Real Madrid", "Wembley"],
      "key_topics": ["football", "sports"],
      "topic_id": "b21e4f90-1234-4a55-9c0d-aa11bb22cc33",
      "primary_country": "GB",
      "country_scope": ["GB", "ES", "FR"]
    }
  ],
  "total": 137,
  "limit": 2,
  "offset": 0
}

#Trend detail

GET/v1/trends/{trend_id}API key

Full detail for one trend: the list fields plus the stable features subset, the 180-day daily sparkline, and created_at/updated_at timestamps.

Path parameters

trend_idstring (UUID)required: The trend to fetch.

curl

curl -s "https://d2tr.com/api/v1/trends/3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "label": "Champions League final",
  "summary": "Coverage of the UEFA Champions League final and build-up.",
  "label_en": "Champions League final",
  "label_ru": "Финал Лиги чемпионов",
  "label_local": null,
  "label_local_lang": null,
  "state": "hot",
  "structural_type": "event_driven",
  "semantic_type": "event_based",
  "semantic_type_confidence": 0.91,
  "article_count": 428,
  "first_seen_at": "2026-05-20T08:14:00+00:00",
  "last_article_at": "2026-05-31T21:07:00+00:00",
  "peak_date": "2026-05-31",
  "expected_next_peak": null,
  "key_entities": ["UEFA", "Real Madrid", "Wembley"],
  "key_topics": ["football", "sports"],
  "topic_id": "b21e4f90-1234-4a55-9c0d-aa11bb22cc33",
  "primary_country": "GB",
  "country_scope": ["GB", "ES", "FR"],
  "daily_counts_180d": [0, 0, 1, 3, 5, 12, 40, "…", 8, 2],
  "features": {
    "days_active": 11,
    "total_articles": 428,
    "slope_14d": 12.7,
    "cv_30d": 0.83,
    "current_share_7d": 0.041,
    "peak_day_ago": 0,
    "first_48h_share": 0.12,
    "acf_30": 0.22,
    "acf_90": 0.10,
    "acf_365": null
  },
  "created_at": "2026-05-20T08:20:00+00:00",
  "updated_at": "2026-05-31T21:10:00+00:00"
}

#Trend articles

GET/v1/trends/{trend_id}/articlesAPI key

Paginated list of the URLs/articles assigned to a trend. The trend-level region gate applies, and for restricted keys articles are additionally filtered to the key’s country_codes.

Path parameters

trend_idstring (UUID)required: The trend whose articles to list.

Query parameters

sort_bystringoptionaldefault first_seen_at: Sort column: first_seen_at, published_at, or assignment_score.
sort_orderstringoptionaldefault desc: asc or desc.
rolestringoptional: Optional trend-role filter: F1_trigger, F2_pile_on, F3_long_tail, or F5_one_off (F4 is not an accepted value).
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Page offset, 0 or greater.

curl

curl -s "https://d2tr.com/api/v1/trends/3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123/articles?role=F1_trigger&sort_by=assignment_score&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "trend_id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "articles": [
    {
      "id": "a17c9e02-4d31-4b88-bb0e-2f9d1c4e7a01",
      "url": "https://www.example-sport.com/ucl-final-recap",
      "title": "Champions League final: full recap",
      "title_en": "Champions League final: full recap",
      "domain": "example-sport.com",
      "publisher": "Example Sport",
      "language": "en",
      "published_at": "2026-05-31T22:05:00+00:00",
      "first_seen_at": "2026-05-31T22:12:00+00:00",
      "summary_en": "A goal-by-goal breakdown of the final…",
      "image_url": "https://cdn.example-sport.com/ucl.jpg",
      "country_code": "GB",
      "assignment_method": "embedding",
      "assignment_score": 0.87,
      "trend_role": "F1_trigger"
    }
  ],
  "total": 1,
  "limit": 2,
  "offset": 0
}

#Trend parents (DAG ancestors)

GET/v1/trends/{trend_id}/parentsAPI key

Direct parent edges of a trend in the genealogy DAG. Not paginated — it returns every direct parent edge. Region-gated: a 404 is returned if the trend isn’t visible to the key.

Path parameters

trend_idstring (UUID)required: The child trend.

curl

curl -s "https://d2tr.com/api/v1/trends/3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123/parents" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "trend_id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
  "parents": [
    {
      "parent_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
      "parent_label": "European football",
      "parent_state": "persistent",
      "parent_structural_type": "evergreen",
      "relation_type": "specialization",
      "strength": 0.74,
      "established_at": "2026-05-21T10:00:00+00:00"
    }
  ]
}

#Trend children (DAG descendants)

GET/v1/trends/{trend_id}/childrenAPI key

Direct child edges of a trend, symmetric to /parents. Not paginated; region-gated with a 404 when the trend isn’t visible to the key.

Path parameters

trend_idstring (UUID)required: The parent trend.

curl

curl -s "https://d2tr.com/api/v1/trends/0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9/children" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "trend_id": "0a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9",
  "children": [
    {
      "child_id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
      "child_label": "Champions League final",
      "child_state": "hot",
      "child_structural_type": "event_driven",
      "relation_type": "specialization",
      "strength": 0.74,
      "established_at": "2026-05-21T10:00:00+00:00"
    }
  ]
}

#List themes

GET/v1/themesAPI key

Top-level hierarchy nodes (level = 2), ordered by n_articles descending. Themes are global metadata and take no query parameters beyond the auth header.

curl

curl -s "https://d2tr.com/api/v1/themes" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "themes": [
    {
      "id": "9c8b7a6d-5e4f-3021-1a2b-3c4d5e6f7081",
      "level": 2,
      "label": "Sports",
      "summary": "All sports coverage across leagues and events.",
      "label_en": "Sports",
      "label_ru": "Спорт",
      "label_local": null,
      "label_local_lang": null,
      "n_trends": 512,
      "n_articles": 84210,
      "parent_id": null,
      "state": null
    }
  ]
}

#Topics under a theme

GET/v1/themes/{theme_id}/topicsAPI key

Child topics (level = 1) of a theme, ordered by n_articles descending. An unknown theme_id yields an empty topics array rather than a 404.

Path parameters

theme_idstring (UUID)required: A level-2 theme node.

curl

curl -s "https://d2tr.com/api/v1/themes/9c8b7a6d-5e4f-3021-1a2b-3c4d5e6f7081/topics" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "theme_id": "9c8b7a6d-5e4f-3021-1a2b-3c4d5e6f7081",
  "topics": [
    {
      "id": "b21e4f90-1234-4a55-9c0d-aa11bb22cc33",
      "level": 1,
      "label": "Football",
      "summary": "Association football / soccer.",
      "label_en": "Football",
      "label_ru": "Футбол",
      "label_local": null,
      "label_local_lang": null,
      "n_trends": 118,
      "n_articles": 30455,
      "parent_id": "9c8b7a6d-5e4f-3021-1a2b-3c4d5e6f7081",
      "state": null
    }
  ]
}

#Trends under a topic

GET/v1/topics/{topic_id}/trendsAPI key

The trend leaves whose topic_id matches, paginated. Items use the same shape as GET /v1/trends, and results are region-scoped for restricted keys.

Path parameters

topic_idstring (UUID)required: A level-1 topic node.

Query parameters

sort_bystringoptionaldefault last_article_at: Sort column: last_article_at, first_seen_at, or article_count.
sort_orderstringoptionaldefault desc: asc or desc.
limitintegeroptionaldefault 50: Page size, 1–200.
offsetintegeroptionaldefault 0: Page offset, 0 or greater.

curl

curl -s "https://d2tr.com/api/v1/topics/b21e4f90-1234-4a55-9c0d-aa11bb22cc33/trends?sort_by=article_count&limit=2" \
  -H "X-API-Key: $D2TR_API_KEY"

Response

{
  "topic_id": "b21e4f90-1234-4a55-9c0d-aa11bb22cc33",
  "trends": [
    {
      "id": "3f8b1c2a-9d44-4e10-8f21-77a0c6b5e123",
      "label": "Champions League final",
      "summary": "Coverage of the UEFA Champions League final and build-up.",
      "label_en": "Champions League final",
      "label_ru": "Финал Лиги чемпионов",
      "label_local": null,
      "label_local_lang": null,
      "state": "hot",
      "structural_type": "event_driven",
      "semantic_type": "event_based",
      "semantic_type_confidence": 0.91,
      "article_count": 428,
      "first_seen_at": "2026-05-20T08:14:00+00:00",
      "last_article_at": "2026-05-31T21:07:00+00:00",
      "peak_date": "2026-05-31",
      "expected_next_peak": null,
      "key_entities": ["UEFA", "Real Madrid", "Wembley"],
      "key_topics": ["football", "sports"],
      "topic_id": "b21e4f90-1234-4a55-9c0d-aa11bb22cc33",
      "primary_country": "GB",
      "country_scope": ["GB", "ES", "FR"]
    }
  ],
  "total": 118,
  "limit": 2,
  "offset": 0
}