News clusters

GET /v1/news/clusters

Lists non-stub story clusters ordered by cluster creation time. Use this for feeds, research queues, or any surface that wants stories rather than individual articles.

Query parameters

Parameter	Type	Notes
start_date	ISO date or datetime	Start of cluster creation window. Defaults to recent clusters.
end_date	ISO date or datetime	End of cluster creation window.
limit	number	Default 25, maximum 100.
offset	number	Default 0.

Response

{
  "clusters": [
    {
      "cluster_id": "cluster_...",
      "cluster_type": "cluster",
      "status": "regular",
      "featured_status": "standard",
      "title": "Example story cluster",
      "abstract": "A short description of the story.",
      "member_count": 8,
      "unique_source_count": 5,
      "source_keys": ["example.com"],
      "key_entities": ["Example Company"],
      "key_ideas": ["Export controls"],
      "first_published_at": "2026-05-07T10:00:00Z",
      "latest_published_at": "2026-05-07T14:03:00Z",
      "latest_member_added_at": "2026-05-07T14:05:00Z",
      "profile_version": 1,
      "created_at": "2026-05-07T14:06:00Z",
      "updated_at": "2026-05-07T14:06:00Z"
    }
  ],
  "limit": 25,
  "offset": 0,
  "next_offset": null,
  "has_more": false
}

GET /v1/news/clusters/{cluster_id}

Fetches one cluster and the articles assigned to it. Looking up a specific cluster ID can return a stub cluster.

Response

{
  "cluster": {
    "cluster_id": "cluster_...",
    "cluster_type": "cluster",
    "title": "Example story cluster",
    "member_count": 8
  },
  "members": [
    {
      "cluster_member_id": "member_...",
      "content_id": "content_...",
      "published_date": "2026-05-07T14:03:00Z",
      "assigned_at": "2026-05-07T14:05:00Z",
      "link_confidence": "high",
      "source_key": "example.com",
      "content_item": {
        "id": "content_...",
        "title": "Example article"
      }
    }
  ]
}