--- title: "News (Vector)" method: POST path: "/v1/vector/news/all" tags: ["v1"] --- # News (Vector) `POST /v1/vector/news/all` Perform a natural language search over news articles from the past 6 months using semantic relevance. The result includes a list of articles most closely matched to your query intent. ## Request body - ArticleSearchParams - `prompt` string, required — Natural language query to search the news articles database - `filter` ArticleSearchFilter — Complex filter structure for article searches that supports nested logical operations (AND, OR, NOT) and multiple filtering criteria. - `articleId` string[], nullable — Filter by specific article identifiers. Accepts either a single ID or an array of IDs. Returns only articles matching these IDs. - `clusterId` string[], nullable — Filter by specific story identifiers. Accepts either a single ID or an array of IDs. Returns only articles belonging to these stories. - `source` string[], nullable — Filter articles by specific publisher domains or subdomains. Accepts either a single domain or an array of domains. Multiple values create an OR filter. - `excludeSource` string[], nullable — Exclude articles from specific publisher domains or subdomains. Accepts either a single domain or an array of domains. Multiple values create an AND-exclude filter. - `sourceGroup` string[], nullable — Filter articles using Perigon's curated publisher bundles (e.g., top100, top25tech). Accepts either a single source group or an array. Multiple values create an OR filter to include articles from any of the specified bundles. - `language` string[], nullable — Filter articles by their language using ISO-639 two-letter codes in lowercase (e.g., en, es, fr). Accepts either a single language code or an array. Multiple values create an OR filter. - `excludeLanguage` string[], nullable — Exclude articles in specific languages using ISO-639 two-letter codes in lowercase. Accepts either a single language code or an array. Multiple values create an AND-exclude filter. - `label` string[], nullable — Filter articles by editorial labels such as Opinion, Paid-news, Non-news, Fact Check, or Press Release. View our docs for an exhaustive list of labels. Accepts either a single label or an array. Multiple values create an OR filter. - `excludeLabel` string[], nullable — Exclude articles with specific editorial labels. Accepts either a single label or an array. Multiple values create an AND-exclude filter, removing all content with any of these labels. - `taxonomy` string[], nullable — Filter by Google Content Categories. Must pass the full hierarchical path of the category. Accepts either a single path or an array. Example: taxonomy=/Finance/Banking/Other,/Finance/Investing/Funds. Multiple values create an OR filter. - `category` string[], nullable — Filter by broad content categories such as Politics, Tech, Sports, Business, or Finance. Accepts either a single category or an array. Use none to find uncategorized articles. Multiple values create an OR filter. - `topic` string[], nullable — Filter by specific topics such as Markets, Crime, Cryptocurrency, or College Sports. Accepts either a single topic or an array. Topics are more granular than categories, and articles can have multiple topics. Multiple values create an OR filter. - `excludeTopic` string[], nullable — Exclude articles with specific topics. Accepts either a single topic or an array. Multiple values create an AND-exclude filter, removing all content with any of these topics. - `country` string[], nullable — Filter articles by countries they mention using two-letter country codes in lowercase (e.g., us, gb, jp). Accepts either a single country code or an array. Multiple values create an OR filter. See documentation for supported country codes. - `excludeCountry` string[], nullable — Exclude articles from specific countries using two-letter country codes in lowercase. Accepts either a single country code or an array. Multiple values create an AND-exclude filter. See documentation for supported country codes. - `locationsCountry` string[], nullable — Filter articles where specified countries play a central role in the content, not just mentioned. Uses two-letter country codes in lowercase. Accepts either a single country code or an array. Multiple values create an OR filter. See documentation for supported country codes. - `excludeLocationsCountry` string[], nullable — Exclude articles where specified countries play a central role in the content. Accepts either a single country code or an array. Multiple values create an AND-exclude filter, removing articles focused on any of these countries. See documentation for supported country codes. - `state` string[], nullable — Filter articles where specified states play a central role in the content. Accepts either a single state code or an array. Multiple values create an OR filter. Uses two-letter state codes in lowercase. See documentation for supported state codes. - `excludeState` string[], nullable — Exclude articles where specified states play a central role. Accepts either a single state code or an array. Multiple values create an AND-exclude filter, removing articles focused on any of these states. See documentation for supported state codes. - `county` string[], nullable — Filter articles that mention or are related to specific counties. Accepts either a single county name or an array. Multiple values create an OR filter. County names typically include the word 'County' (e.g., Los Angeles County). - `excludeCounty` string[], nullable — Exclude articles that mention or are related to specific counties. Accepts either a single county name or an array. Multiple values create an AND-exclude filter. County names should match the format in article metadata (e.g., Los Angeles County, Cook County). - `city` string[], nullable — Filter articles that mention or are related to specific cities. Accepts either a single city name or an array. Multiple values create an OR filter. - `excludeCity` string[], nullable — Exclude articles that mention or are related to specific cities. Accepts either a single city name or an array. Multiple values create an AND-exclude filter. - `sourceCountry` string[], nullable — Filter for articles from publishers based in specific countries. Accepts either a single country code or an array. Uses two-letter country codes in lowercase (e.g., us, gb). See documentation for supported country codes. - `sourceState` string[], nullable — Filter for articles from publishers based in specific states or regions. Accepts either a single state code or an array. Uses two-letter state codes in lowercase. See documentation for supported state codes. - `sourceCounty` string[], nullable — Filter for articles from publishers based in specific counties. Accepts either a single county name or an array. Multiple values create an OR filter. - `sourceCity` string[], nullable — Filter for articles from publishers based in specific cities. Accepts either a single city name or an array. Multiple values create an OR filter. - `coordinates` CoordinateFilter — Filter articles from publishers based at specific geographic locations. Uses latitude, longitude, and radius parameters to define a circular search area for publisher locations. - `lat` number, float, nullable - `lon` number, float, nullable - `radius` number, float, nullable - `sourceCoordinates` CoordinateFilter — Filter articles from publishers based at specific geographic locations. Uses latitude, longitude, and radius parameters to define a circular search area for publisher locations. - `lat` number, float, nullable - `lon` number, float, nullable - `radius` number, float, nullable - `companyId` string[], nullable — Filter articles by company identifiers. Accepts either a single ID or an array. Multiple values create an OR filter. For a complete list of tracked companies and their IDs, refer to the /companies endpoint. - `excludeCompanyId` string[], nullable — Exclude articles mentioning companies with specific identifiers. Accepts either a single ID or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their IDs, refer to the /companies endpoint. - `companyDomain` string[], nullable — Filter articles by company domains (e.g., apple.com). Accepts either a single domain or an array. Multiple values create an OR filter. For a complete list of tracked companies and their domains, refer to the /companies endpoint. - `excludeCompanyDomain` string[], nullable — Exclude articles related to companies with specific domains. Accepts either a single domain or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their domains, refer to the /companies endpoint. - `companySymbol` string[], nullable — Filter articles by company stock symbols (e.g., AAPL, MSFT). Accepts either a single symbol or an array. Multiple values create an OR filter. For a complete list of tracked companies and their symbols, refer to the /companies endpoint. - `excludeCompanySymbol` string[], nullable — Exclude articles related to companies with specific stock symbols. Accepts either a single symbol or an array. Multiple values create an AND-exclude filter. For a complete list of tracked companies and their symbols, refer to the /companies endpoint. - `companyName` string[], nullable — Filter articles by company name mentions. Accepts either a single name or an array. Performs exact matching on company names. Multiple values create an OR filter. For a complete list of tracked companies and their names, refer to the /companies endpoint. - `personWikidataId` string[], nullable — Filter articles by Wikidata IDs of mentioned people. Accepts either a single ID or an array. Multiple values create an OR filter. For a complete list of tracked individuals and their Wikidata IDs, refer to the /people endpoint. - `excludePersonWikidataId` string[], nullable — Exclude articles mentioning people with specific Wikidata IDs. Accepts either a single ID or an array. Multiple values create an AND-exclude filter. For a complete list of tracked individuals and their Wikidata IDs, refer to the /people endpoint. - `personName` string[], nullable — Filter articles by exact person name matches. Accepts either a single name or an array. Does not support Boolean operators or wildcards. Multiple values create an OR filter. For a complete list of tracked individuals and their names, refer to the /people endpoint. - `excludePersonName` string[], nullable — Exclude articles mentioning specific people by name. Accepts either a single name or an array. Multiple values create an AND-exclude filter. For a complete list of tracked individuals and their names, refer to the /people endpoint. - `AND` ArticleSearchFilter[], nullable — Adds additional AND filter objects. These objects must be of the same type as the original filter object and will be combined with the existing filter using the AND logical operator. - `OR` ArticleSearchFilter[], nullable — Adds additional OR filter objects. These objects must be of the same type as the original filter object and will be combined with the existing filter using the OR logical operator. - `NOT` ArticleSearchFilter[], nullable — A filter object for logical NOT operations - `pubDateFrom` string, date-time, nullable — 'pubDateFrom' filter, will search articles published after the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Date time in ISO format, ie. 2024-01-01T00:00:00 - Default: Only articles with a pubDate within the last 30 days of the request - `pubDateTo` string, date-time, nullable — 'pubDateTo' filter, will search articles published before the specified date, the date could be passed as ISO or 'yyyy-mm-dd'. Date time in ISO format, ie. 2024-01-01T00:00:00 - `showReprints` boolean, nullable — Whether to return reprints in the response or not. Reprints are usually wired articles from sources like AP or Reuters that are reprinted in multiple sources at the same time. By default, this parameter is 'true'. - `size` integer, nullable — The number of items per page. - `page` integer, nullable — The page number to retrieve. ## Response `200` 200 - Success - ArticlesVectorSearchResult — Articles vector search result - `status` integer, required - `results` ScoredDataArticle[], required - `score` number, float, nullable - `data` Article - `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 - `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 - … - `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 - `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 - `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 - `vectors` VectorData[], nullable - `data` number[], nullable - `version` integer, 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 optional property `results/items/data/allOf[#/components/schemas/Article]/cluster/allOf[#/components/schemas/NewsCluster]/sourceDiversity` to the response with the `200` status - added the optional property `results/items/data/allOf[#/components/schemas/Article]/vectors` to the response with the `200` status - **2026-04-30** `182b74871f6a` — 2 info - added the optional property `results/items/data/allOf[#/components/schemas/Article]/cluster/allOf[#/components/schemas/NewsCluster]/locations/items/country` to the response with the `200` status - added the optional property `results/items/vectors` to the response with the `200` status - **2025-09-26** `41e61f364687` — 1 info - added the optional property `results/items/data/allOf[#/components/schemas/Article]/enContentWordCount` to the response with the `200` status - **2025-08-18** `a73a3b58ca66` — 1 breaking, 22 warning, 81 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 - …100 more - …earlier changes not shown [Full history](https://skmtc.dev/goperigon/apis/perigon-api/changes/v1/vector/news/all/post.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)