#

Storylines

Track a storyline, not a feed of articles. AskNews Storylines follows what the world is covering as it develops. Each storyline is one persistent object: the articles that cover it, from outlets across countries and languages, clustered together, with a new update written whenever the storyline develops.

Every update is written from a deliberately diverse set of sources, cites the articles it draws on, and comes as structured analytics an agent can act on: what is new, where sources contradict each other, how coverage and sentiment are moving, which people and organizations are involved, and what Reddit is saying.

API Storylines are served by the stories endpoints (GET /v1/stories, GET /v1/stories/{story_id}) and the stories scope. Each storyline is a Story object, and each of its developments an update.

Explore storylines in the AskNews WebUI, and see the full schema in the API reference.

#

What are Storylines

• Widely-covered storylines, followed for their whole life. The news corpus is clustered into persistent storylines, and a storyline is tracked once enough outlets cover it: selection is by breadth of coverage, not by clicks or engagement. New coverage joins the storyline it belongs to as an update, so one ID follows a storyline from its first report through every development. There is no limit on how long a storyline is tracked: it keeps receiving updates for as long as it keeps developing, and only stops once its coverage has gone quiet for about two weeks.
• Diverse sources by design. The articles each update is written from (prompt_articles) are chosen for diversity: at most one per outlet, sampled in proportion to the cluster's mix of source countries, so no single outlet or country sets the narrative. An update is only written when those articles span at least five different outlets, and its markdown_citations trace each claim back to the article it came from.
• Coverage you can measure. Each update reports its outlets (sources_urls), source countries (countries_pct, where the outlets are based) and languages (languages_pct), so you can see how widely a storyline is covered and by whom, not just what is said about it.
• What changed, and where sources disagree. Each update separates new_information from the background, lists key_takeaways, and surfaces contradictions: the claims the coverage does not agree on. It also rates the coverage's reporting_voice and how provocative it is, with a confidence score derived from the generation's token log probabilities (a measure of the model's certainty, not a probability that the update is true).
• Analytics through time. The storyline carries a time series per update: articles (n_articles), sentiment and rolling_sentiment, and Reddit sentiment. See whether a storyline is gaining or losing coverage, and whether the tone is shifting.
• Entities and how they connect. Each update lists its people, organizations, locations and other entities (extracted with our open-source GLiNER News model) and the relationships between them as a graph.
• The social signal. Where a storyline is discussed on Reddit, the update includes a Reddit perspective and, on request, the threads themselves.

Storylines are not Alerts. Alerts tell you when something happens. Storylines tell you what's happening, and how it got there. Alerts follow what you define: your query and schedule, delivered as a notification or report. Storylines are the record of what the world is covering: each storyline's history, what changed, and how its coverage is moving. Many teams use both: find a storyline in Storylines, then set an Alert for the developments that matter to them.

Storylines is built as an analytics layer for agentic workflows. Common uses include:

• Discovering what the world is covering. An agent lists the storylines in play right now, by category or region, without needing a query, including the ones nobody thought to set an alert for.
• Consuming only what changed. An agent keeps a storyline's uuid, comes back on its own schedule, and reads only the new updates (update_uuids, new_information) instead of re-processing the coverage.
• Checking claims against their sources. An agent sees where outlets disagree (contradictions), which countries and languages drive the coverage, and traces each claim to its article before it repeats it.
• Analyzing storylines as data. Every storyline carries a per-update series of coverage and sentiment, ready for research pipelines, dashboards or forecasting features.
• Grounding answers in a storyline's full context. Hand a model the current state and history of a storyline, cited and source-diverse, instead of raw search results.

#

Story object

The Story object is what the stories endpoints return: one storyline and everything aggregated about it. Fields include (but are not limited to):

• uuid: A unique identifier for the storyline.
• updates: The storyline's updates, newest first. Each carries the AskNews-written update, its clustered articles and its analytics (see the update object below).
• update_uuids: The UUIDs of all the storyline's updates, oldest first.
• n_articles: A time series of the storyline's coverage, one value per update.
• sentiment and rolling_sentiment: A time series of the coverage's sentiment, one value per update, and its rolling average.
• sentiment_timestamps: The time of each value in the series above.
• reddit_sentiment: A time series of sentiment on Reddit.
• sources, countries_pct, languages_pct: The outlets that covered the storyline, and the share of coverage by source country and language.
• people, locations: The people and locations most relevant to the storyline.
• categories: The storyline's categories.

A full representation of the Story object can be found in the API reference.

With the story.uuid you can always come back for the storyline's latest state. The aggregated fields (such as sentiment, n_articles and updates) grow as new coverage arrives:

#

Update object

Each storyline's updates holds its developments. Every update includes (but is not limited to):

• uuid: A unique identifier for the update.
• headline: The update's headline.
• story: The AskNews-written account of the update, with citations.
• new_information: What this update adds to what was known.
• key_takeaways: The update's key points.
• contradictions: Where the sources disagree.
• cluster_articles: The articles clustered into this update.
• prompt_articles: The articles the update was written from, selected for outlet and country diversity.
• n_articles: The number of articles in this update's cluster.
• sources_urls: Each outlet and how many articles it contributed.
• countries_pct and languages_pct: The update's coverage by source country and language.
• entities: The people, organizations, locations and other entities mentioned, by type.
• relationships: How those entities connect, as nodes and edges.
• reporting_voice and provocative: How the coverage reports the update, and how provocative it is.
• confidence: The update's confidence, from the generated tokens' log probabilities.
• reddit_perspective and reddit_threads: The Reddit discussion of the update.
• story_update_ts: When the update was made.
• story_uuid: The storyline the update belongs to.
• image_url: The update's image.

A full representation of the update object can be found in the API reference.

#

Searching storylines

AskNews filters include (but are not limited to):

• query: A natural language or keyword query to filter storylines (optional)
• method: Method to use for query, 'nl' means natural language, 'kw' means keyword, and 'both' means that both methods will be used and results will be ranked according to IRR (optional)
• obj_type: Object type to filter by, can be a list with 'story' and/or 'story_update'. Searching with obj_type="story" finds storylines by their most recent update. To search through every update, use obj_type="story_update" (optional)
• categories: Filter storylines by category (optional)
• continent: Filter storylines by the continent of their coverage (optional)
• uuids: Get an exact list of storylines by their UUIDs (optional)
• start_timestamp: Filter storylines by start timestamp (optional)
• end_timestamp: Filter storylines by end timestamp (optional)
• reddit: The number of reddit threads to include in the response (optional)
• sort_by: Sort storylines by published date, coverage, sentiment, relevance, or confidence (optional)
• sort_type: Sort in ascending or descending order (optional)
• offset: Offset to use for pagination (optional)
• limit: Limit to use for pagination (optional)
• expand_updates: Whether to get all the details for the storyline's updates. Setting this to False will result in a faster response time. (optional)
• max_updates: Maximum number of updates to obtain for a single storyline. Setting this to 1 will result in the fastest response time. (optional)
• max_articles: Maximum number of articles to include for each update. If you use storylines for clustering, set this high to get the full cluster of articles. (optional)
• citation_method: The method to use for citations in the story.updates[].story field. Can be 'brackets', 'urls', or 'none'. Use 'urls' if you want to get the citations injected in markdown format (e.g. (AOL)[https://aol.com]), use 'brackets' to get citations injected as integers in square brackets (e.g. [1]) which correspond to the index in update.prompt_articles list. Use 'none' if you do not want any citations (optional).

A full view of the available parameters is available in the API reference.

#

The most-covered technology storylines in North America

To get the technology and science storylines with the most coverage in North America, combine the category and continent filters and sort by coverage:

This prints the headlines of the most-covered technology storylines in North America from the past 24 hours. To control the time period, set start_timestamp and end_timestamp.

#

Searching storylines with a query

You can search storylines and their updates with natural language or keywords. For example, to find storylines that mention "TSLA" and were updated in the last 24 hours:

Or, for a semantic search on "Tesla's stock is sky-rocketing!" across every update as well as the latest:

#

Getting one storyline or update by UUID or title

Pass a story.uuid or an update.url_safe_title to get_story to retrieve one storyline with much higher limits for max_updates and max_articles. A story.uuid returns the storyline with its latest update; an update.url_safe_title returns the storyline with that update as its requested_update_uuid. An update.uuid is not a lookup key for one update: it returns the parent storyline's latest updates.

To get more than the latest update, pass max_updates (up to 10). By default the other updates come back condensed, to two prompt articles and no cluster; set condense_auxillary_updates=False to receive every update in full:

You can also set max_articles, and the number of Reddit threads with reddit.

A full view of the available parameters is available in the API reference.