---
title: "Filter and search for top news narratives"
method: GET
path: "/v1/stories"
tags: ["stories"]
---

# Filter and search for top news narratives

`GET /v1/stories`

Filter on our custom, in-house written, stories/events/narratives.

These stories are based on clusters of articles (which come through this
endpoint as well, so you can consider this a clustering endpoint). We write
stories and track them through time.

The enrichments include a full Reddit overview (including all the thread metadata),
as well as descriptions of the reporting voice, the key takeaways, contradictions,
all the entities, and much, much more.

You can see this data in action, and filter it similarly at
`https://asknews.app/stories`

## Query parameters

- `query` string, nullable — Query to be used for the search. If method='nl', then this will beused as a natural language query. If method='kw', then this willbe used as a direct keyword query.
- `categories` string[] — Categories to use for filtering the stories search
- `uuids` string[] — A list of UUIDs to retrieve.
- `start_timestamp` integer, nullable — Start timestamp to filter results on.
- `end_timestamp` integer, nullable — End timestamp to filter results on.
- `sort_by` 'published' | 'coverage' | 'sentiment' | 'relevance' | 'confidence', nullable — Which type of sorting to perform. published: Sort by published date. coverage: Sort by coverage. sentiment: Sort by sentiment. relevance: Sort by relevance of similarity score/ranking.
- `sort_type` 'asc' | 'desc', nullable — Whether to sort results in ascending or descending order.
- `continent` union — Continents to filter by.
  - string[]
  - string
- `offset` union — Offset to use
  - integer
  - string
- `limit` integer — Limit to use
- `expand_updates` boolean — Whether to expand updates
- `max_updates` integer — Max updates to use
- `max_articles` integer — Max articles to use per update
- `method` 'nl' | 'kw' | 'both' — Method to use for query, 'nl' means natural language, and will run a semantic search on the stories database. 'kw' means keyword, and will search by keyword on the stories database. 'both' means that both methods will be used and results will be ranked according to IRR.
- `obj_type` string[] — Object type to filter by, can be a list with 'story' and/or 'story_update'
- `reddit` integer — Whether or not to include Reddit analysiswhere the integer indicates the number of threadsto include in the response. 0 is default. Requirespaid plan to access.
- `citation_method` 'brackets' | 'urls' | 'none' — Method to use for citation filtering.
- `similarity_score_threshold` number — Similarity score threshold to use when using query
- `provocative` 'unknown' | 'low' | 'medium' | 'high' | 'all' — Filter stories based on how provocative the underlying articles are deemed based on the use of provocative language and emotional vocabulary.
- `strategy` 'default' | 'topstories' | 'topstories_categories' | 'topstories_continents' — Strategy to use for automatically controlling the search. 'default' is the default strategy, which follows all filters faithfully. 'topstories' aims to give a diverse look at top news stories that are relevant to the current filter combination.'topstories_categories' aims to give the top stories for each category. 'topstories_continents' aims to give the top stories for each continent.

## Response `200`

A list of stories with updates

- StoriesResponse
  - `stories` StoryResponse[], required
    - `uuid` string, uuid, required
    - `categories` string[], required
    - `countries` object, required
    - `countries_pct` object, required
    - `current_update_uuid` string, required
    - `requested_update_uuid` string, required
    - `generate_image` boolean, required
    - `keywords` string[], required
    - `languages` object, required
    - `languages_pct` object, required
    - `locations` string[], required
    - `meta_type` string, required
    - `n_articles` integer[], required
    - `n_updates` integer, required
    - `people` string[], required
    - `reddit_sentiment` union[], required
      - union
        - integer
        - number
    - `reddit_sentiment_timestamps` integer[], required
    - `rolling_sentiment` number[], required
    - `sentiment` integer[], required
    - `sentiment_timestamps` integer[], required
    - `sources` object, required
    - `sources_urls` object, required
    - `topic` string, required
    - `topics` string[], required
    - `updates` StoryUpdate[], required
      - `uuid` string, uuid, required
      - `cluster_articles` Article[], required
        - `article_url` string, uri, required
        - `article_id` string, uuid, required
        - `classification` union, required
          - string[]
          - string
        - `country` string, required
        - `source_id` string, required
        - `page_rank` integer, required
        - `domain_url` string, required
        - `eng_title` string, required
        - `entities` Entities, required
          - `Person` string[]
          - `Organization` string[]
          - `Location` string[]
          - `Nationality` string[]
          - `Date` string[]
          - `Event` string[]
          - `Money` string[]
          - `Law` string[]
          - `Quantity` string[]
          - `Time` string[]
          - `Sports` string[]
          - `Politics` string[]
          - `Title` string[]
          - `Number` string[]
          - `Arms` string[]
          - `Product` string[]
          - `Media` string[]
          - `Transportation` string[]
          - `Religion` string[]
          - `Technology` string[]
          - `Space` string[]
          - `Medicine` string[]
          - `Language` string[]
          - `Science` string[]
        - `image_url` string, nullable
        - `keywords` string[], required
        - `language` string, required
        - `pub_date` string, date-time, required
        - `summary` string, required
        - `key_points` string[], nullable
        - `title` string, required
        - `sentiment` integer, required
        - `centroid_distance` number, required
        - `cluster_probability` number, required
        - `markdown_citation` string
        - `provocative` 'unknown' | 'low' | 'medium' | 'high'
        - `reporting_voice` union
          - 'Objective' | 'Subjective' | 'Investigative' | 'Narrative' | 'Analytical' | 'Advocacy' | 'Conversational' | 'Satirical' | 'Emotive' | 'Explanatory' | 'UnknownPersuasive' | 'Sensational'
          - string
        - `entity_relation_graph` AsknewsApiSchemaV1CommonGraphRelationships
          - `nodes` object[]
          - `edges` object[]
        - `geo_coordinates` object, nullable
        - `continent` 'Africa' | 'Asia' | 'Europe' | 'Middle East' | 'North America' | 'South America' | 'Oceania', nullable
        - `assets` Assets
          - `images` string[], nullable
          - `videos` string[], nullable
        - `social_embeds` string[], nullable
        - `bias` 'Political' | 'Gender' | 'Cultural' | 'Age' | 'Religious' | 'Statement' | 'Illogical Claims' | 'Slant' | 'Source Selection' | 'Omission of Source Attribution' | 'Spin' | 'Sensationalism' | 'Negativity' | 'Subjective Adjectives' | 'Ad Hominem' | 'Mind Reading' | 'Opinion-as-Fact' | 'None' | 'Unknown', nullable
        - `authors` Author[], nullable
          - `email` string, nullable
          - `name` string, nullable
          - `url` string, nullable
        - `full_text` string, nullable
        - `original_language_summary` string, nullable
        - `image_description` string, nullable
        - `crawl_date` string, date-time, nullable
        - `content_type` 'news' | 'opinion' | 'analysis' | 'review' | 'listicle' | 'guide' | 'interview' | 'profile' | 'forum' | 'liveblog' | 'fact-check' | 'press_release' | 'obituary' | 'data_journalism', nullable
      - `prompt_articles` Article[], required
        - `article_url` string, uri, required
        - `article_id` string, uuid, required
        - `classification` union, required
          - string[]
          - string
        - `country` string, required
        - `source_id` string, required
        - `page_rank` integer, required
        - `domain_url` string, required
        - `eng_title` string, required
        - `entities` Entities, required
          - `Person` string[]
          - `Organization` string[]
          - `Location` string[]
          - `Nationality` string[]
          - `Date` string[]
          - `Event` string[]
          - `Money` string[]
          - `Law` string[]
          - `Quantity` string[]
          - `Time` string[]
          - `Sports` string[]
          - `Politics` string[]
          - `Title` string[]
          - `Number` string[]
          - `Arms` string[]
          - `Product` string[]
          - `Media` string[]
          - `Transportation` string[]
          - `Religion` string[]
          - `Technology` string[]
          - `Space` string[]
          - `Medicine` string[]
          - `Language` string[]
          - `Science` string[]
        - `image_url` string, nullable
        - `keywords` string[], required
        - `language` string, required
        - `pub_date` string, date-time, required
        - `summary` string, required
        - `key_points` string[], nullable
        - `title` string, required
        - `sentiment` integer, required
        - `centroid_distance` number, required
        - `cluster_probability` number, required
        - `markdown_citation` string
        - `provocative` 'unknown' | 'low' | 'medium' | 'high'
        - `reporting_voice` union
          - 'Objective' | 'Subjective' | 'Investigative' | 'Narrative' | 'Analytical' | 'Advocacy' | 'Conversational' | 'Satirical' | 'Emotive' | 'Explanatory' | 'UnknownPersuasive' | 'Sensational'
          - string
        - `entity_relation_graph` AsknewsApiSchemaV1CommonGraphRelationships
          - `nodes` object[]
          - `edges` object[]
        - `geo_coordinates` object, nullable
        - `continent` 'Africa' | 'Asia' | 'Europe' | 'Middle East' | 'North America' | 'South America' | 'Oceania', nullable
        - `assets` Assets
          - `images` string[], nullable
          - `videos` string[], nullable
        - `social_embeds` string[], nullable
        - `bias` 'Political' | 'Gender' | 'Cultural' | 'Age' | 'Religious' | 'Statement' | 'Illogical Claims' | 'Slant' | 'Source Selection' | 'Omission of Source Attribution' | 'Spin' | 'Sensationalism' | 'Negativity' | 'Subjective Adjectives' | 'Ad Hominem' | 'Mind Reading' | 'Opinion-as-Fact' | 'None' | 'Unknown', nullable
        - `authors` Author[], nullable
          - `email` string, nullable
          - `name` string, nullable
          - `url` string, nullable
        - `full_text` string, nullable
        - `original_language_summary` string, nullable
        - `image_description` string, nullable
        - `crawl_date` string, date-time, nullable
        - `content_type` 'news' | 'opinion' | 'analysis' | 'review' | 'listicle' | 'guide' | 'interview' | 'profile' | 'forum' | 'liveblog' | 'fact-check' | 'press_release' | 'obituary' | 'data_journalism', nullable
      - `n_articles` integer, required
      - `entities` Entities, required
        - `Person` string[]
        - `Organization` string[]
        - `Location` string[]
        - `Nationality` string[]
        - `Date` string[]
        - `Event` string[]
        - `Money` string[]
        - `Law` string[]
        - `Quantity` string[]
        - `Time` string[]
        - `Sports` string[]
        - `Politics` string[]
        - `Title` string[]
        - `Number` string[]
        - `Arms` string[]
        - `Product` string[]
        - `Media` string[]
        - `Transportation` string[]
        - `Religion` string[]
        - `Technology` string[]
        - `Space` string[]
        - `Medicine` string[]
        - `Language` string[]
        - `Science` string[]
      - `headline` string, required
      - `story` string, required
      - `story_update_ts` integer, required
      - `sources_urls` object, required
      - `languages_pct` object, required
      - `countries_pct` object, required
      - `key_takeaways` string[], required
      - `contradictions` string[], required
      - `continent` string, required
      - `people` string[], required
      - `locations` string[], required
      - `new_information` string, required
      - `image_url` string, uri, required
      - `url_safe_title` string, required
      - `story_uuid` string, uuid, required
      - `categories` string[], required
      - `image_prompt` string, required
      - `reddit_perspective` RedditPerspective, required
        - `sentiment` union, required
          - integer
          - number
        - `relevant` boolean, required
        - `summary` string, required
      - `reddit_threads` RedditThread[], required
        - `author` string, required
        - `author_comment_karma` integer, required
        - `author_link_karma` integer, required
        - `body` string, required
        - `classification` union, required
          - string[]
          - string
        - `comments` RedditComment[], required
          - `author` string, required
          - `body` string, required
          - `date` string, date-time, required
          - `upvotes` integer, required
        - `comments_count` integer, required
        - `date` string, date-time, required
        - `entities` RedditEntities, required
          - `DATE` string[]
          - `EVENT` string[]
          - `GPE` string[]
          - `ORG` string[]
          - `PERSON` string[]
          - `NORP` string[]
          - `CARDINAL` string[]
        - `id` string, uuid, required
        - `key_takeaways` string[]
        - `keywords` string[], required
        - `sentiment` union, required
          - integer
          - number
        - `subreddit_name` string, required
        - `subreddit_url` string, required
        - `summary` string, required
        - `title` string, required
        - `topic` string, required
        - `upvotes` integer, required
        - `url` string, required
        - `main_speculation` string
      - `languages` object, required
      - `keywords` string[], required
      - `intra_cluster_statistics` IntraClusterStatistics, required
        - `cluster_articles_pct` number
        - `cluster_countries_pct` number
        - `cluster_domains_pct` number
        - `cluster_languages_pct` number
        - `cluster_probabilities` object
      - `silhouette_score` object, required
      - `article_ids` string[], required
      - `countries` object, required
      - `markdown_citations` string[], required
      - `confidence` number
      - `provocative` 'unknown' | 'low' | 'medium' | 'high'
      - `reporting_voice` string
      - `relationships` AsknewsApiSchemaV1StoriesGraphRelationships, required
        - `nodes` object[], required
        - `edges` object[], required
      - `mermaid` string, required
      - `cc_image_url` string, required
      - `display_image_urls` union[], required
        - union
          - DisplayImageUrl
            - `source_id` string, required
            - `image_url` string, uri, required
          - string
      - `alignment` integer
    - `updated_ts` integer, required
    - `update_uuids` string[], required
  - `offset` union, required
    - integer
    - string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `405` — Method Not Allowed
- `422` — Unprocessable Entity
- `500` — Internal Server Error

---

[API](https://skmtc.dev/asknews/apis/asknews-api.md) · [All operations](https://skmtc.dev/asknews/apis/asknews-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/asknews/asknews-api/revisions/dd4286769887/schema)