--- title: "Stories" method: GET path: "/v1/stories/all" tags: ["v1"] --- # Stories `GET /v1/stories/all` 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. ## Query parameters - `q` string - `name` string - `clusterId` string[] - `excludeClusterId` string[] - `sortBy` 'createdAt' | 'updatedAt' | 'relevance' | 'count' | 'totalCount' - `page` integer - `size` integer - `from` string, date-time - `to` string, date-time - `initializedFrom` string, date-time - `initializedTo` string, date-time - `updatedFrom` string, date-time - `updatedTo` string, date-time - `topic` string[] - `category` string[] - `taxonomy` string[] - `source` string[] - `sourceGroup` string[] - `minUniqueSources` integer - `minSourceDiversity` number - `personWikidataId` string[] - `personName` string - `companyId` string[] - `companyName` string - `companyDomain` string[] - `companySymbol` string[] - `country` string[] - `state` string[] - `city` string[] - `area` string[] - `minClusterSize` integer - `maxClusterSize` integer - `nameExists` boolean - `positiveSentimentFrom` number, float - `positiveSentimentTo` number, float - `neutralSentimentFrom` number, float - `neutralSentimentTo` number, float - `negativeSentimentFrom` number, float - `negativeSentimentTo` number, float - `showStoryPageInfo` boolean - `showNumResults` boolean - `showDuplicates` boolean - `showHighlighting` boolean - `highlightFragmentSize` integer - `highlightNumFragments` integer - `highlightPreTag` string - `highlightPostTag` string - `highlightQ` string - `expandArticles` boolean ## Response `200` 200 - Success - StorySearchResult — Story search result - `status` integer, required - `numResults` integer, required - `results` NewsCluster[], required - `createdAt` string, nullable - `updatedAt` string, nullable - `initializedAt` string, nullable - `id` string, nullable - `duplicateOf` string, nullable - `slug` string, nullable - `name` string, nullable - `summary` string, nullable - `shortSummary` string, nullable - `summaryReferences` string[], nullable - `imageSource` SourceHolder - `domain` string, nullable - `paywall` boolean, nullable - `location` SourceLocation - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `coordinates` Coordinate - `lat` number, double, nullable - `lon` number, double, nullable - `imageUrl` string, nullable - `keyPoints` KeyPoint[], nullable - `point` string, nullable - `references` string[], nullable - `questions` Question[], nullable - `question` string, nullable - `answer` string, nullable - `references` string[], nullable - `uniqueSources` string[], nullable - `selectedArticles` Article[], nullable - `url` string, nullable - `authorsByline` string, nullable - `articleId` string, nullable - `clusterId` string, nullable - `source` SourceHolder - `domain` string, nullable - `paywall` boolean, nullable - `location` SourceLocation - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `coordinates` Coordinate - `lat` number, double, nullable - `lon` number, double, nullable - `imageUrl` string, nullable - `country` string, nullable - `language` string, nullable - `pubDate` string, nullable - `addDate` string, nullable - `refreshDate` string, nullable - `score` number, float, nullable - `title` string, nullable - `description` string, nullable - `content` string, nullable - `enContentWordCount` integer, nullable - `medium` string, nullable - `links` string[], nullable - `labels` LabelHolder[], nullable - `name` string, nullable - `eventTypes` EventTypeHolder[], nullable - `name` string, nullable - `type` string, nullable - `matchedAuthors` IdNameHolder[], nullable - `id` string, nullable - `name` string, nullable - `claim` string, nullable - `verdict` string, nullable - `keywords` KeywordHolder[], nullable - `name` string, nullable - `weight` number, float, nullable - `topics` TopicHolder[], nullable - `name` string, nullable - `categories` CategoryHolder[], nullable - `name` string, nullable - `taxonomies` CategoryWithScoreHolder[], nullable - `name` string, nullable - `score` number, double, nullable - `entities` EntityHolder[], nullable - `data` string, nullable - `type` string, nullable - `mentions` integer, nullable - `companies` CompanyHolder[], nullable - `id` string, nullable - `name` string, nullable - `domains` string[], nullable - `symbols` string[], nullable - `sentiment` SentimentHolder - `positive` number, float, nullable - `negative` number, float, nullable - `neutral` number, float, nullable - `summary` string, nullable - `shortSummary` string, nullable - `translation` string, nullable - `translatedTitle` string, nullable - `translatedDescription` string, nullable - `translatedSummary` string, nullable - `locations` LocationHolder[], nullable - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `area` string, nullable - `reprint` boolean, nullable - `reprintGroupId` string, nullable - `places` Place[], nullable - `osmId` string, nullable - `road` string, nullable - `quarter` string, nullable - `suburb` string, nullable - `city` string, nullable - `town` string, nullable - `county` string, nullable - `stateDistrict` string, nullable - `state` string, nullable - `postcode` string, nullable - `country` string, nullable - `countryCode` string, nullable - `amenity` string, nullable - `neighbourhood` string, nullable - `coordinates` Coordinate - `lat` number, double, nullable - `lon` number, double, nullable - `people` PersonHolder[], nullable - `wikidataId` string, nullable - `name` string, nullable - `cluster` NewsCluster — recursive - `journalists` Journalist[], nullable - `id` string, nullable - `name` string, nullable - `fullName` string, nullable - `headline` string, nullable - `description` string, nullable - `title` string, nullable - `locations` LocationHolder[], nullable - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `area` string, nullable - `updatedAt` string, nullable - `topTopics` NameCount[], nullable - `name` string, nullable - `count` integer, nullable - `topSources` NameCount[], nullable - `name` string, nullable - `count` integer, nullable - `topCategories` NameCount[], nullable - `name` string, nullable - `count` integer, nullable - `topLabels` NameCount[], nullable - `name` string, nullable - `count` integer, nullable - `topCountries` NameCount[], nullable - `name` string, nullable - `count` integer, nullable - `avgMonthlyPosts` integer, nullable - `twitterHandle` string, nullable - `twitterBio` string, nullable - `imageUrl` string, nullable - `linkedinUrl` string, nullable - `linkedinConnections` integer, nullable - `linkedinFollowers` integer, nullable - `facebookUrl` string, nullable - `instagramUrl` string, nullable - `websiteUrl` string, nullable - `blogUrl` string, nullable - `tumblrUrl` string, nullable - `youtubeUrl` string, nullable - `highlights` object, nullable - `vectors` VectorData[], nullable - `data` number[], nullable - `version` integer, nullable - `sentiment` SentimentHolder - `positive` number, float, nullable - `negative` number, float, nullable - `neutral` number, float, nullable - `uniqueCount` integer, nullable - `reprintCount` integer, nullable - `totalCount` integer, nullable - `countries` RecordStatHolder[], nullable - `name` string, nullable - `count` integer, nullable - `topCountries` string[], nullable - `topics` RecordStatHolder[], nullable - `name` string, nullable - `count` integer, nullable - `topTopics` TopicHolder[], nullable - `name` string, nullable - `categories` RecordStatHolder[], nullable - `name` string, nullable - `count` integer, nullable - `topCategories` CategoryHolder[], nullable - `name` string, nullable - `taxonomies` RecordStatHolder[], nullable - `name` string, nullable - `count` integer, nullable - `topTaxonomies` CategoryHolder[], nullable - `name` string, nullable - `people` PersonCount[], nullable - `wikidataId` string, nullable - `name` string, nullable - `count` integer, nullable - `topPeople` PersonHolder[], nullable - `wikidataId` string, nullable - `name` string, nullable - `companies` CompanyCount[], nullable - `id` string, nullable - `name` string, nullable - `domains` string[], nullable - `symbols` string[], nullable - `count` integer, nullable - `topCompanies` CompanyHolder[], nullable - `id` string, nullable - `name` string, nullable - `domains` string[], nullable - `symbols` string[], nullable - `locations` LocationCount[], nullable - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `area` string, nullable - `count` integer, nullable - `topLocations` LocationHolder[], nullable - `country` string, nullable - `state` string, nullable - `county` string, nullable - `city` string, nullable - `area` string, nullable - `highlights` object, nullable - `sourceDiversity` number, double, nullable ## Other responses - `400` — 400 - Bad Request - `401` — 401 - Invalid API Key - `403` — 403 - Request Forbidden - `429` — 429 - Too Many Requests - `500` — 500 - Server Error ## Changes - **2026-05-07** `2c55bf07003a` — 2 info - added the new optional `query` request parameter `minSourceDiversity` - added the optional property `results/items/sourceDiversity` to the response with the `200` status - **2026-04-30** `182b74871f6a` — 1 info - added the optional property `results/items/locations/items/country` to the response with the `200` status - **2025-08-18** `a73a3b58ca66` — 1 breaking, 22 warning, 79 info - the `status` response's property type/format changed from `string`/`` to `integer`/`int32` for status `429` - removed the optional property `cause` from the response with the `400` status - removed the optional property `cause` from the response with the `401` status - removed the optional property `cause` from the response with the `403` status - …98 more - **2025-08-04** `3eb8ae4622b8` — 12 breaking, 49 warning, 6 info - the response property `results/items/imageSource` became nullable for the status `200` - the response property `results/items/selectedArticles/items/cluster` became nullable for the status `200` - the response property `results/items/selectedArticles/items/places/items/coordinates` became nullable for the status `200` - the response property `results/items/selectedArticles/items/sentiment` became nullable for the status `200` - …63 more - …earlier changes not shown [Full history](https://skmtc.dev/goperigon/apis/perigon-api/changes/v1/stories/all/get.md) --- [API](https://skmtc.dev/goperigon/apis/perigon-api.md) · [All operations](https://skmtc.dev/goperigon/apis/perigon-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/goperigon/perigon-api/revisions/2c55bf07003a/schema)