v17

latestOpenAPI 3.0.1raw.githubusercontent.com2026-05-072674388.0 KB
v1

Stories

Track evolving narratives and top news headlines with the 'Stories' endpoint — it returns structured clusters of related articles with summaries, key points, sentiment scores, and metadata on top people, companies, topics, countries, and categories. Use it to monitor how news stories develop over time, who and what they impact, and where they're gaining traction globally.

Each story represents a cluster of related articles grouped during processing. Articles are assigned to a single story, identified by the clusterId field. Once a story reaches five articles, a story title is automatically generated based on its content. Stories update as new coverage is processed and key details evolve.

To fetch all articles within a specific story, query the /articles/all endpoint using the clusterId parameter.

get/v1/stories/all

Query parameters

qstring

String. Primary search query for filtering stories based on their name, summary, and key points. Supports Boolean operators (AND, OR, NOT), exact phrases with quotes, and wildcards (* and ?) for flexible searching.

namestring

String. Search specifically within story names. Supports Boolean operators, exact phrases with quotes, and wildcards for matching name variations.

clusterIdstring[]

String Array. Filter to specific stories using their unique identifiers. Each clusterId represents a distinct story that groups related articles. Multiple values create an OR filter.

excludeClusterIdstring[]

String Array. Excludes specific stories from the results by their unique identifiers. Use this parameter to filter out unwanted or previously seen stories.

sortBy'createdAt' | 'updatedAt' | 'relevance' | 'count' | 'totalCount'

String. Determines the story sorting order. Options include createdAt (default, when stories first emerged), updatedAt (when stories received new articles, best for tracking developing events), relevance (best match to query), count (by unique article count), and totalCount (by total article count including reprints).

pageinteger

Integer. The specific page of results to retrieve in the paginated response. Starts at 0.

sizeinteger

Integer. The number of articles to return per page in the paginated response.

fromstring date-time

Date. 'from' filter, will search stories created after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T00:00:00

tostring date-time

Date. 'to' filter, will search stories created before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Add time in ISO format, ie. 2023-03-01T23:59:59

initializedFromstring date-time

Date. Filter for stories created after this date. Alternative parameter for filtering by story creation date.

initializedTostring date-time

Date. Filter for stories created before this date. Alternative parameter for filtering by story creation date.

updatedFromstring date-time

Date. Filter for stories that received new articles after this date. Useful for tracking developing news events or evolving storylines.

updatedTostring date-time

Date. Filter for stories that received new articles before this date. Useful for tracking developing news events or evolving storylines.

topicstring[]

String Array. Filter stories by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Topics are more granular than categories, and stories can include multiple topics based on their constituent articles. Use the /topics endpoint for a complete list of available topics. Multiple values create an OR filter.

categorystring[]

String Array. Filter stories by broad content categories such as Politics, Tech, Sports, Business, or Finance. Use 'none' to find uncategorized stories. Categories are derived from the articles within each story. Multiple values create an OR filter.

taxonomystring[]

String Array. Filter stories by Google Content Categories. Must pass the full hierarchical path of the category. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Stories are categorized based on their constituent articles. Multiple values create an OR filter.

sourcestring[]

String Array. Filter stories that contain articles from specific publisher domains or subdomains. Supports wildcards (* and ?) for pattern matching (e.g., *.cnn.com). A story will match if it contains at least one article from any of the specified sources. Multiple values create an OR filter.

sourceGroupstring[]

String Array. Filter stories that contain articles from publishers in Perigon's curated bundles (e.g., top100, top25crypto). A story will match if it contains at least one article from any publisher in the specified bundles. Multiple values create an OR filter.

minUniqueSourcesinteger

Integer. Specifies the minimum number of unique sources required for a story to appear in results. Higher values return more significant stories covered by multiple publications. Default is 3.

minSourceDiversitynumber

Float. Minimum ratio of unique sources to unique articles (uniqueSources / uniqueCount). Filters out stories dominated by a single publisher. For example, a value of 0.05 requires at least 1 unique source per 20 articles. Not applied by default.

personWikidataIdstring[]

String Array. Filter stories by Wikidata IDs of top mentioned people. Returns stories where these individuals appear prominently. Refer to the /people endpoint for a complete list of tracked individuals.

personNamestring

String. Filter stories by exact name matches of top mentioned people. Does not support Boolean or complex logic. For available person entities, consult the /people endpoint.

companyIdstring[]

String Array. Filter stories by identifiers of top mentioned companies. Returns stories where these companies appear prominently. For a complete list of tracked companies, refer to the /companies endpoint.

companyNamestring

String. Filter stories by names of top mentioned companies. Performs an exact match on company names in the topCompanies field.

companyDomainstring[]

String Array. Filter stories by domains of top mentioned companies (e.g., apple.com). Returns stories where companies with these domains appear prominently. For available company entities, consult the /companies endpoint.

companySymbolstring[]

String Array. Filter stories by stock symbols of top mentioned companies. Returns stories where companies with these symbols appear prominently. For available company entities and their symbols, consult the /companies endpoint.

countrystring[]

String Array. Country code to filter by country. If multiple parameters are passed, they will be applied as OR operations.

statestring[]

String Array. Filter local news by state. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.

citystring[]

String Array. Filter local news by city. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.

areastring[]

String Array. Filter local news by area. Applies only to local news, when this param is passed non-local news will not be returned. If multiple parameters are passed, they will be applied as OR operations.

minClusterSizeinteger

Integer. Filter by minimum cluster size. Minimum cluster size filter applies to number of unique articles.

maxClusterSizeinteger

Integer. Filter by maximum cluster size. Maximum cluster size filter applies to number of unique articles in the cluster.

nameExistsboolean

Boolean. Filter to only include stories that have been assigned names. Defaults to true. Note that stories only receive names after they contain at least 5 unique articles.

positiveSentimentFromnumber float

Float. Filter articles with an aggregate positive sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.

positiveSentimentTonumber float

Float. Filter articles with an aggregate positive sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger positive tone.

neutralSentimentFromnumber float

Float. Filter articles with an aggregate neutral sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.

neutralSentimentTonumber float

Float. Filter articles with an aggregate neutral sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger neutral tone.

negativeSentimentFromnumber float

Float. Filter stories with an aggregate negative sentiment score greater than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.

negativeSentimentTonumber float

Float. Filter articles with an aggregate negative sentiment score less than or equal to the specified value. Scores range from 0 to 1, with higher values indicating stronger negative tone.

showStoryPageInfoboolean

Boolean.

showNumResultsboolean

Boolean. Show total number of results. By default set to false, will cap result count at 10000.

showDuplicatesboolean

Boolean. Stories are deduplicated by default. If a story is deduplicated, all future articles are merged into the original story. duplicateOf field contains the original cluster Id. When showDuplicates=true, all stories are shown.

showHighlightingboolean

Boolean. When set to true, enables text highlighting in search results.

highlightFragmentSizeinteger

Integer. Specifies the size in characters of each highlighted text fragment. Defaults to 100 if not specified.

highlightNumFragmentsinteger

Integer. Controls the maximum number of highlighted fragments to return per field.

highlightPreTagstring

String. Defines the HTML tag that appears before highlighted text. Defaults to '<em>' if not specified.

highlightPostTagstring

String. Defines the HTML tag that appears after highlighted text. Defaults to '</em>' if not specified.

highlightQstring

String. Specifies a separate query for highlighting, allowing highlights based on terms different from the main search query. Example: main query 'q=climate change' with 'highlightQ=renewable OR solar' will highlight terms 'renewable' and 'solar' in results about climate change.

expandArticlesboolean

Boolean. Preview 5 articles from the cluster.

Response

200 - Success

statusinteger required
numResultsinteger required

Example response

{
  "status": 200,
  "numResults": 10000,
  "results": [
    {
      "createdAt": "2025-08-12T09:26:15.861525+00:00",
      "updatedAt": "2025-08-12T09:47:42.780519+00:00",
      "initializedAt": "2025-08-12T09:43:09.364043+00:00",
      "id": "c9b6bebef14943edb6269c80b1cb51c5",
      "name": "Red Bull Completes Newcastle Rugby Takeover, Rebrands Club",
      "summary": "Red Bull has completed a takeover of the Premiership Rugby club Newcastle Falcons, rebranding the team as Newcastle Red Bulls while keeping them at Kingston Park. The acquisition marks Red Bull's first significant involvement in rugby union and brings fresh investment aimed at elevating the club's competitive potential domestically and in Europe. Steve Diamond will remain as director of rugby, ensuring continuity as the club seeks to compete for trophies in the coming years. Red Bull plans to develop local rugby talent through an enhanced academy program and enhance the fan experience by applying their innovative approach from global sports initiatives. Premiership Rugby CEO Simon Massie-Taylor hailed the takeover as a landmark moment that will add value to both Newcastle and the league, emphasizing Red Bull's expertise in high-performance sports and marketing. The club, established in 1877 and historically known as Newcastle Falcons, aims to leverage Red Bull's global sports portfolio, which includes Formula 1 and various football clubs, to grow its fanbase and player pathway in the North East.",
      "shortSummary": "Energy drink giant Red Bull has completed a takeover of Newcastle Falcons rugby club, rebranding it as Newcastle Red Bulls and keeping it at Kingston Park with Steve Diamond remaining as director of rugby. Red Bull aims to elevate the club's competitive potential, develop local talent through an enhanced academy, and leverage their global sports expertise to boost both the club and the Gallagher Premiership.",
      "summaryReferences": [
        "66c3a007e2374ffdbbaa70ee5e251693",
        "e32349ed5e084f71be1e28733755ed7e",
        "558dc91a9ab04630908404ca4221d2fb",
        "f73d2117e50d4cfb8740ed3384b2b330",
        "c1c65a3e5bc34ab1ab9f049986a53cc1"
      ],
      "keyPoints": [
        {
          "point": "The previous owner Semore Kurdi had put the club up for sale at a nominal price of £1 due to financial struggles, signaling the club was on the brink of a financial crisis before Red Bull's takeover.",
          "references": []
        },
        {
          "point": "Newcastle Rugby Ltd highlighted the club’s long history, originally established in 1877 as Gosforth Football Club and undergoing several name changes before becoming Newcastle Falcons in 1996, and now Newcastle Red Bulls in 2025.",
          "references": []
        },
        {
          "point": "Newcastle Falcons have a decorated history, having won five major titles including the Premiership in 1998 and four domestic cups in 1976, 1977, 2001, and 2004.",
          "references": []
        },
        {
          "point": "Red Bull's global sports portfolio includes ownership stakes in multiple football clubs such as RB Leipzig, New York Red Bulls, Red Bull Salzburg, Red Bull Bragantino, and minority stakes in Paris FC and Leeds United, illustrating their extensive experience in sports ownership and management.",
          "references": []
        },
        {
          "point": "Red Bull has a history of working with prominent rugby players such as Springboks captain Siya Kolisi and former England international Jack Nowell, indicating their prior engagement with rugby despite this being their first significant club ownership in rugby union.",
          "references": []
        }
      ],
      "sentiment": {
        "positive": 0.6500967,
        "negative": 0.112720154,
        "neutral": 0.23718315
      },
      "uniqueCount": 6,
      "reprintCount": 3,
      "totalCount": 9,
      "countries": [
        {
          "name": "gb",
          "count": 5
        },
        {
          "name": "ca",
          "count": 3
        },
        {
          "name": "za",
          "count": 1
        }
      ],
      "topCountries": [
        "gb"
      ],
      "topics": [
        {
          "name": "Rugby",
          "count": 2
        }
      ],
      "topTopics": [
        {
          "name": "Rugby"
        }
      ],
      "categories": [
        {
          "name": "Sports",
          "count": 5
        }
      ],
      "topCategories": [
        {
          "name": "Sports"
        }
      ],
      "taxonomies": [
        {
          "name": "/News/Sports News",
          "count": 8
        },
        {
          "name": "/Sports/Team Sports/Rugby",
          "count": 8
        }
      ],
      "topTaxonomies": [
        {
          "name": "/News/Sports News"
        },
        {
          "name": "/Sports/Team Sports/Rugby"
        }
      ],
      "people": [
        {
          "wikidataId": "Q15837487",
          "name": "Oliver Mintzlaff",
          "count": 8
        },
        {
          "wikidataId": "Q7612382",
          "name": "Steve Diamond",
          "count": 5
        },
        {
          "wikidataId": "Q7533339",
          "name": "Siya Kolisi",
          "count": 2
        },
        {
          "wikidataId": "Q15731077",
          "name": "Jack Nowell",
          "count": 2
        },
        {
          "wikidataId": "Q7612383",
          "name": "Steve Diamond",
          "count": 3
        },
        {
          "wikidataId": "Q5229992",
          "name": "Dave Thompson",
          "count": 1
        },
        {
          "wikidataId": "Q104535295",
          "name": "Jamie Blamire",
          "count": 2
        },
        {
          "wikidataId": "Q50124849",
          "name": "Callum Chick",
          "count": 2
        },
        {
          "wikidataId": "Q74698940",
          "name": "Tom Christie",
          "count": 2
        },
        {
          "wikidataId": "Q19519831",
          "name": "Max Clark",
          "count": 1
        }
      ],
      "topPeople": [
        {
          "wikidataId": "Q15837487",
          "name": "Oliver Mintzlaff"
        },
        {
          "wikidataId": "Q7612382",
          "name": "Steve Diamond"
        }
      ],
      "companies": [
        {
          "id": "d19eef21be0343e4b96c73b85f5afed9",
          "name": "Premiership Rugby",
          "domains": [
            "premiershiprugby.com"
          ],
          "symbols": [],
          "count": 7
        },
        {
          "id": "c28c867e3ec84f569eb0c2c202ffec20",
          "name": "Red Bull GmbH",
          "domains": [
            "redbull.com"
          ],
          "symbols": [],
          "count": 7
        },
        {
          "id": "1986c4e2c8b54e81af4fbae3e8fbb870",
          "name": "The Raine Group",
          "domains": [
            "raine.com"
          ],
          "symbols": [],
          "count": 2
        },
        {
          "id": "d79a8b400c5c4f12bbbda5b4ac95d882",
          "name": "TNT Sports",
          "domains": [
            "wbd.com",
            "discoverysports.com"
          ],
          "symbols": [],
          "count": 4
        },
        {
          "id": "932cd2db2347407fbda9386cb18307dc",
          "name": "Deloitte",
          "domains": [
            "deloitte.com"
          ],
          "symbols": [],
          "count": 2
        },
        {
          "id": "b40dc389506141a4bcd5ba94f64592f6",
          "name": "Red Bull",
          "domains": [
            "redbullracing.com"
          ],
          "symbols": [],
          "count": 6
        },
        {
          "id": "f1e3e2243cd142408136bd8f43282c4a",
          "name": "City A.M.",
          "domains": [
            "cityam.com"
          ],
          "symbols": [],
          "count": 1
        },
        {
          "id": "c4800bcde1c940d6b13e2022836c10cd",
          "name": "Getty Images Holdings, Inc.",
          "domains": [
            "gettyimages.com"
          ],
          "symbols": [
            "GETY"
          ],
          "count": 2
        },
        {
          "id": "1bc09603d6cd4aeba01c8c7762d8cda6",
          "name": "Reuters",
          "domains": [
            "reuters.com"
          ],
          "symbols": [],
          "count": 1
        },
        {
          "id": "fb9806c8e362406ea89d48d31dcf50a7",
          "name": "Formula One Group",
          "domains": [
            "libertymedia.com"
          ],
          "symbols": [
            "0JUJ.L",
            "FWONA",
            "FWONB",
            "FWONK"
          ],
          "count": 1
        },
        {
          "id": "01a4555587844344a5b0eef0854ee0ad",
          "name": "Guardian Media Group",
          "domains": [
            "theguardian.com"
          ],
          "symbols": [],
          "count": 1
        }
      ],
      "topCompanies": [
        {
          "id": "d19eef21be0343e4b96c73b85f5afed9",
          "name": "Premiership Rugby",
          "domains": [
            "premiershiprugby.com"
          ],
          "symbols": []
        },
        {
          "id": "c28c867e3ec84f569eb0c2c202ffec20",
          "name": "Red Bull GmbH",
          "domains": [
            "redbull.com"
          ],
          "symbols": []
        },
        {
          "id": "b40dc389506141a4bcd5ba94f64592f6",
          "name": "Red Bull",
          "domains": [
            "redbullracing.com"
          ],
          "symbols": []
        }
      ],
      "locations": [
        {
          "state": "ENG",
          "city": "Newcastle upon Tyne",
          "count": 2
        }
      ],
      "topLocations": [
        {
          "state": "ENG",
          "city": "Newcastle upon Tyne"
        }
      ]
    }
  ]
}