clstr

Search the news by topic to find matching situations and events. A situation is an ongoing storyline (story arc) that groups related events over time; an event, called a cluster, is one happening assembled from many outlets and deduplicated into a single item, so you get one event rather than 20 near-duplicate headlines. Results come back grouped under their situations, each with a one-line summary, a significance score (1 to 10, where 8 and above is exceptional), a source count (how many outlets are covering it), and a canonical clstr.news link. Use this to answer 'what is happening around X' for a topic, company, country, or event. Then open a result with get_situation_timeline for the full history, or get_cluster for one event's detail. Results are relevance ordered and bounded to the top matches: when there are more, the result ends with a cursor to pass back, and each page counts as one search against your cap. Pass summary: "full" to read each match's summary untruncated instead of one line. Cite the returned URLs. (Requires sign-in, or a free API key: https://clstr.news/developers)

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Topic, entity, company, country, or event to search for.",
      "maxLength": 200
    },
    "days": {
      "type": "integer",
      "minimum": 1,
      "maximum": 30,
      "description": "How far back to search, in days. Default 7, maximum 30."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "Max events to return. Default 15. They are grouped under their situations in the result, so you may see fewer situation headings than this number."
    },
    "summary": {
      "type": "string",
      "enum": [
        "preview",
        "full"
      ],
      "description": "How much summary text each row carries. 'preview' (the default) is a one-line preview; 'full' returns the maintained summary in full, so you do not need a follow-up call per result. On get_top_situations, 'full' is not enabled for every account: read `summary_mode` in the result to see which mode was actually served, and get_situation_timeline always returns one situation's summary in full."
    },
    "cursor": {
      "type": "string",
      "description": "From a previous result, to page further. Each page counts as one search against your cap."
    }
  },
  "required": [
    "query"
  ]
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": "string"
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "significance_score": {
            "type": [
              "integer",
              "null"
            ],
            "description": "AI-generated significance, 1 to 10, where 8 and above is exceptional."
          },
          "sources": {
            "type": "integer",
            "minimum": 0,
            "description": "How many outlets are behind this event."
          },
          "published_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO-8601 UTC timestamp."
          },
          "updated_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO-8601 UTC timestamp."
          },
          "url": {
            "type": "string",
            "description": "Canonical clstr.news URL. Cite this."
          },
          "situation": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "slug": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "cluster_count": {
                "type": "integer",
                "minimum": 0
              }
            }
          }
        }
      }
    },
    "query": {
      "type": "object",
      "description": "The query as actually run: `days` is the EFFECTIVE window after tier and index clamps.",
      "properties": {
        "q": {
          "type": "string"
        },
        "days": {
          "type": "integer",
          "minimum": 1
        }
      },
      "required": [
        "q",
        "days"
      ]
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass back as cursor to page further. Each page is one search."
    },
    "summary_mode": {
      "type": "string",
      "enum": [
        "preview",
        "full"
      ],
      "description": "The summary mode this result was served in, which is not always the one requested."
    }
  },
  "required": [
    "data",
    "query",
    "next_cursor",
    "summary_mode"
  ]
}

Get the full chronological timeline of one situation. A situation is an ongoing storyline (story arc) that groups related news events over time; it carries a maintained summary plus every event in order, so you see not just what happened but how it developed. Each event is a cluster (one happening assembled from many outlets and deduplicated) with its date, a significance score (1 to 10, where 8 and above is exceptional), a source count, and a canonical clstr.news link. Use this to brief on a story's history or answer 'how did this develop'. Get a situation id from search_situations or get_top_situations, or from a clstr.news URL. An id that was retired when two situations merged resolves to the successor, flagged with merged_into_shown. Cite the returned URLs.

{
  "type": "object",
  "properties": {
    "situation_id": {
      "type": "string",
      "description": "Situation id or slug (from other tools or clstr.news URLs)."
    },
    "timeline_limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 50,
      "description": "Timeline entries to return, newest first. Default 50, and 50 is also the maximum without an API key. A free key raises it to 500: https://clstr.news/developers"
    },
    "timeline_before": {
      "type": "string",
      "description": "Cursor: cluster id (a UUID) from a previous page, to continue past it."
    }
  },
  "required": [
    "situation_id"
  ]
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "summary": {
          "type": "string",
          "description": "The maintained situation summary, in full."
        },
        "summary_preview": {
          "type": "string"
        },
        "cluster_count": {
          "type": "integer",
          "minimum": 0
        },
        "source_count": {
          "type": "integer",
          "minimum": 0
        },
        "first_seen": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 UTC timestamp."
        },
        "last_updated": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 UTC timestamp."
        },
        "status": {
          "type": [
            "string",
            "null"
          ],
          "description": "ACTIVE or QUIET."
        },
        "category": {
          "type": [
            "string",
            "null"
          ]
        },
        "categories": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "significance_score": {
          "type": [
            "integer",
            "null"
          ],
          "description": "AI-generated significance, 1 to 10, where 8 and above is exceptional."
        },
        "latest_cluster_title": {
          "type": [
            "string",
            "null"
          ]
        },
        "url": {
          "type": "string",
          "description": "Canonical clstr.news URL. Cite this."
        },
        "is_timeline_page": {
          "type": "boolean",
          "description": "True on a timeline_before continuation page, which omits the header fields."
        },
        "timeline": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "slug": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "summary": {
                "type": "string"
              },
              "category": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "countries": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "significance_score": {
                "type": [
                  "integer",
                  "null"
                ],
                "description": "AI-generated significance, 1 to 10, where 8 and above is exceptional."
              },
              "sources": {
                "type": "integer",
                "minimum": 0,
                "description": "How many outlets are behind this event."
              },
              "published_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO-8601 UTC timestamp."
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO-8601 UTC timestamp."
              },
              "url": {
                "type": "string",
                "description": "Canonical clstr.news URL. Cite this."
              }
            }
          },
          "description": "Member events, newest first."
        },
        "timeline_cursor": {
          "type": "object",
          "properties": {
            "has_more": {
              "type": "boolean"
            },
            "next_before": {
              "type": [
                "string",
                "null"
              ],
              "description": "Pass back as timeline_before for the next page."
            },
            "remaining_count": {
              "type": "integer",
              "minimum": 0
            },
            "total_count": {
              "type": [
                "integer",
                "null"
              ]
            }
          }
        },
        "day_span": {
          "type": "integer",
          "minimum": 0
        },
        "merged_into_shown": {
          "type": "boolean",
          "description": "Present when a retired id was served as its successor."
        },
        "requested_id": {
          "type": "string",
          "description": "The retired id that was asked for, alongside merged_into_shown."
        }
      },
      "required": [
        "is_timeline_page",
        "timeline",
        "timeline_cursor"
      ]
    }
  },
  "required": [
    "data"
  ]
}

List the situations developing right now, ranked by relevance: a blend of significance, how many outlets are covering it, and how recently it moved. So a lower significance score can rank above a higher one, and that ordering is intentional; do not re-sort. A situation is an ongoing storyline that groups related news events over time and carries a maintained summary and a source count (how many outlets are behind it). Optionally filter by category, by country, and by time window (24h, 7d, or 30d), and switch the ordering to newest activity first with sort. Use this to answer 'what is going on in the world', 'what is happening in <category>' or 'what is happening in <country>' when there is no specific topic yet, then open any result with get_situation_timeline. When there are more, the result ends with a cursor to page further. Pass summary: "full" to get each situation's maintained summary in full, instead of a one-line preview, without a follow-up call per result; full summaries in a list are not enabled for every account, so read summary_mode in the result to see what you got, and use get_situation_timeline for one situation's summary in full. Cite the returned URLs.

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "politics",
        "business",
        "technology",
        "health",
        "sports",
        "culture",
        "international",
        "crime"
      ],
      "description": "Optional category filter."
    },
    "country": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional country filter: comma-separated ISO 3166-1 alpha-2 codes, for example \"US,GB\". Up to 10 at once. A situation matches if it is covered in any of them."
    },
    "window": {
      "type": "string",
      "enum": [
        "24h",
        "7d",
        "30d"
      ],
      "description": "Time window. Default '7d'."
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "recent"
      ],
      "description": "Ordering. 'relevance' (the default) blends significance, source count and recency; 'recent' is newest activity first."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 25,
      "description": "Max situations to return. Default 15."
    },
    "summary": {
      "type": "string",
      "enum": [
        "preview",
        "full"
      ],
      "description": "How much summary text each row carries. 'preview' (the default) is a one-line preview; 'full' returns the maintained summary in full, so you do not need a follow-up call per result. On get_top_situations, 'full' is not enabled for every account: read `summary_mode` in the result to see which mode was actually served, and get_situation_timeline always returns one situation's summary in full. 'full' returns each situation's complete summary, up to roughly 300 words per row, so keep limit small when you use it."
    },
    "cursor": {
      "type": "string",
      "description": "From a previous result, to page further. Pass the same filters alongside it: a cursor resumes only under the filter set that produced it."
    }
  },
  "required": []
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": [
              "string",
              "null"
            ]
          },
          "title": {
            "type": [
              "string",
              "null"
            ]
          },
          "summary": {
            "type": "string",
            "description": "The maintained situation summary, in full. Present only when summary: \"full\" was requested."
          },
          "summary_preview": {
            "type": "string"
          },
          "cluster_count": {
            "type": "integer",
            "minimum": 0
          },
          "source_count": {
            "type": "integer",
            "minimum": 0
          },
          "first_seen": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO-8601 UTC timestamp."
          },
          "last_updated": {
            "type": [
              "string",
              "null"
            ],
            "description": "ISO-8601 UTC timestamp."
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "ACTIVE or QUIET."
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "categories": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "countries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "ISO 3166-1 alpha-2 codes."
          },
          "significance_score": {
            "type": [
              "integer",
              "null"
            ],
            "description": "AI-generated significance, 1 to 10, where 8 and above is exceptional."
          },
          "latest_cluster_title": {
            "type": [
              "string",
              "null"
            ]
          },
          "url": {
            "type": "string",
            "description": "Canonical clstr.news URL. Cite this."
          }
        }
      }
    },
    "next_cursor": {
      "type": [
        "string",
        "null"
      ],
      "description": "Pass back as cursor to page further. Null at the end."
    },
    "summary_mode": {
      "type": "string",
      "enum": [
        "preview",
        "full"
      ],
      "description": "The summary mode this result was served in, which is not always the one requested."
    },
    "window_days": {
      "type": "integer",
      "minimum": 1,
      "description": "The time window this result covers, in days, which is not always the one requested."
    }
  },
  "required": [
    "data",
    "next_cursor",
    "summary_mode",
    "window_days"
  ]
}

Get one news event in detail. A cluster is a single real-world event assembled from many outlets covering the same happening and deduplicated into one item, so you get one event rather than 20 near-duplicate headlines. Returns its summary, a significance score (1 to 10, where 8 and above is exceptional), a source count, the situation it belongs to if any, and its underlying source articles with links. It returns up to 100 representative articles, one per source; `sources` and `articles_total` are the full count, and `articles_truncated` says whether the list was cut. Use this when the user wants the specifics of one event. Get a cluster id from search_situations, get_situation_timeline, or a clstr.news URL. Cite the returned URLs. (Requires sign-in, or a free API key: https://clstr.news/developers)

{
  "type": "object",
  "properties": {
    "cluster_id": {
      "type": "string",
      "description": "Cluster id or slug (from timelines, search, or clstr.news URLs)."
    },
    "articles": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "description": "How many source articles to return, 1 to 100. Default 100. Lower it when you only need a few citations; the source count is reported separately and is unaffected."
    }
  },
  "required": [
    "cluster_id"
  ]
}

{
  "type": "object",
  "properties": {
    "data": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        },
        "summary": {
          "type": "string",
          "description": "The short summary."
        },
        "category": {
          "type": [
            "string",
            "null"
          ]
        },
        "countries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "significance_score": {
          "type": [
            "integer",
            "null"
          ],
          "description": "AI-generated significance, 1 to 10, where 8 and above is exceptional."
        },
        "sources": {
          "type": "integer",
          "minimum": 0,
          "description": "How many outlets are behind this event."
        },
        "published_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 UTC timestamp."
        },
        "updated_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "ISO-8601 UTC timestamp."
        },
        "url": {
          "type": "string",
          "description": "Canonical clstr.news URL. Cite this."
        },
        "summary_full": {
          "type": "string",
          "description": "The full narrative summary."
        },
        "keywords": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "articles": {
          "type": "array",
          "description": "The underlying source articles.",
          "items": {
            "type": "object",
            "properties": {
              "source_host": {
                "type": "string"
              },
              "url": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The outlet's own URL, null when it could not be published."
              },
              "title": {
                "type": "string"
              },
              "published_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "ISO-8601 UTC timestamp."
              }
            }
          }
        },
        "articles_total": {
          "type": "integer",
          "minimum": 0,
          "description": "How many outlets are behind this event in total. `articles` is capped, this is not."
        },
        "articles_truncated": {
          "type": "boolean",
          "description": "True when `articles` holds fewer entries than `articles_total`."
        },
        "situation": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "title": {
              "type": [
                "string",
                "null"
              ]
            },
            "slug": {
              "type": [
                "string",
                "null"
              ]
            },
            "cluster_count": {
              "type": "integer",
              "minimum": 0
            }
          }
        },
        "merged_into_shown": {
          "type": "boolean",
          "description": "Present when a merged-away event was served as its successor."
        }
      },
      "required": [
        "articles",
        "articles_total",
        "articles_truncated"
      ]
    }
  },
  "required": [
    "data"
  ]
}