#

Stories

AskNews stories provide quick access to the hottest topics in the news-sphere, filterable by coverage, region, category, and sentiment. Further, AskNews stories provide high-level overview of the news landscape with custom written content based on human-in-the-loop editorial. Common uses for AskNews stories include:

• 🧭 Clustering and deduplication: AskNews uses state-of-the-art clustering, deduplication, and diversification algorithms to generate clean clusters of news articles for each story. This means that each story that you obtain in AskNews is infact a cluster of unique news articles from across the news landscape.
• 📈 Identifying hot topics: Quickly filter regions or categories according to global attention. Answer the question "What is the most popular news story in technology right now?"
• 💌 Tracking sentiment and coverage: Monitor the sentiment or coverage of news narratives through time. Get updates to stories in real-time by hittingthe endpoint with a Answer the question "is this topic increasing in popularity/sentiment or decreasing in popularity/sentiment?"
• 📰 Republish content: AskNews stories are custom written overviews with human-in-the-loop editorial. The content is ready to be republished in any format you choose*.
• 🤖 Training data: AskNews stories are generated by leading SOTA LLMs, making them great training data for fine-tuning local models to speak like AskNews. Further, the data is highly enriched with entities, graphs of relationships, and clustering analytics.

*All inputs used for generating AskNews stories are custom written summaries of news articles across the news landscape. This means that AskNews stories do not derive from or contain any text scraped from the web, which in-turn means that all AskNews content is licensable for your own commercial use (at the enterprise tier).

#

Story object

The Story object is the object that is returned from the stories endpoint. It is an aggregation of information concerning a single news narrative (e.g. the evolution of ). This object contains a variety of aggregated information, including (but not limited to) the following fields:

• uuid: A unique identifier for the story.
• sentiment: A list representing the time-series of sentiment as it has evolved for this story through time.
• n_articles: A list representing the time-series of coverage as it has evolved for this story through time.
• reddit_sentiment: A list representing the time-series of sentiment as it has evolved for this story through time on Reddit.
• locations: A list of locations that are relevant to the story.
• people: A list of people that are relevant to the story.
• sources: A list of sources that have covered the story.
• countries: A list of countries that the sources derive from.
• updates: A list of updates to the story. Each update contains the custom AskNews story, the clustered articles for that update, and a variety of other information.
• update_uuids: A list of UUIDs that represent all the updates associated with the story.

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

Given the story.uuid, you can always return and obtain the latest updates to the story. This is useful for tracking the evolution of a story through time. The aggregated information (such as sentiment, reddit_sentiment, updates etc.) will be updated in real-time as new information is added to the story:

#

Update object

The story object always contains a list of updates. Each update object contains a variety of information concerning a single update to the story. This includes (but is not limited to) the following fields:

• uuid: A unique identifier for the update.
• cluster_articles: A list of articles that are clustered together for this update.
• prompt_articles: A list of articles that are used to generate the custom AskNews story for this update.
• n_articles: The number of articles that are clustered together for this update.
• entities: A list of entities that are relevant to the story.
• headline: The headline of the story update.
• story: The custom AskNews story for this update.
• story_update_ts: The timestamp of the story update.
• sources_urls: A dictionary of sources and the number of articles that they have contributed to the story.
• languages_pct: A dictionary of languages and the percentage of articles that are written in that language.
• key_takeaways: A list of key takeaways from the story update.
• contradictions: A list of contradictions in the story update.
• image_url: The URL of the image associated with the story update.
• story_uuid: The UUID of the story that this update is associated with.
• reddit_perspective: The Reddit perspective for the story update.
• reddit_threads: A list of Reddit threads that are associated with the story update.
• confidence: The story confidence based on the generated token logprobabilities.

A full representation of the update object can be found in the response object of the story endpoint - API reference.

#

Searching through stories

AskNews filters include (but are not limited to):

• query: A natural language or keyword query to filter stories (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" will find stories according to the most recent update. If you want to search through all updates, use obj_type="story_update(optional)
• categories: Filter stories by category (optional)
• continent: Filter stories by continent (optional)
• uuids: Get an exact list of stories by their UUIDs (optional)
• start_timestamp: Filter stories by start timestamp (optional)
• end_timestamp: Filter stories by end timestamp (optional)
• reddit: The number of reddit threads to include in the response (optional)
• sort_by: Sort stories by published date, coverage, sentiment, relevance, or confidence (optional)
• sort_type: Sort stories by sentiment in ascending or descending order (optional)
• continent: Filter stories by continent (optional)
• offset: Offset to use for pagination (optional)
• limit: Limit to use for pagination (optional)
• expand_updates: Whether to get all the details for updates in the story or not. Setting this to False will result in a faster response time. (optional)
• max_updates: Maximum number of updates to obtain for a single story. 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 are using stories for clustering, you will want to set this number 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.

#

Getting the hottest tech stories in North America

If you would like to obtain the hottest tech stories in North America, you can use the filters as follows:

Which will print out the headline of the top technology stories in North America from the past 24 hours. If you would like to control the time period of your search, you can also define the start_timestamp and end_timestamp parameters.

#

Using a query to search through stories

You can use natural language or keyword queries to search through stories and story updates. For example, if you would like to search for stories that contain the keyword "TSLA" and have been updated in the last 24 hours, you can use the following query:

Or if you would like to use a semantic search on "Tesla stock is skyrocketing!", and you'd like to search on updates as well, you can use the following query:

#

Getting a single story or update by UUID or title

If you have a story.uuid, update.uuid or update.url_safe_title, you can pass this value to the get_story function to retrieve the document with a much higher limits for max_updates and max_articles. In the case of passing a story.uuid, it will return the story object with the latest update in story.updates. If you pass a specific update.uuid or update.url_safe_title, it will return the specific update object in story.updates:

If you would like to obtain more than just the latest update, you can pass the max_updates parameter to the get_story function:

You can also control the max_articles parameter as well as the number of reddit threads with the reddit parameters.

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