Articles endpoint

GET /v1/articles

Returns articles matching the given filters. All parameters are optional; a request with no filters returns the most recent articles across your plan’s coverage.

Query parameters

Parameter	Type	Description
`q`	string	Search term, up to 191 characters. Required when `search=semantic`.
`search`	`keyword` \| `boolean` \| `semantic`	How `q` is matched. Default `keyword`. See Search modes.
`search_in`	`title` \| `title_body`	Whether `q` is matched against the headline only or the headline and article text. Default `title`. Not applicable to `search=semantic`.
`country`	`NL` \| `BE` \| `LU`	Country of the publishing outlet. Accepts multiple values.
`language`	`nl` \| `fr` \| `de` \| `lb` \| `en`	Article language. Accepts multiple values.
`has_author`	boolean	`true` returns only articles with a named author; `false` only those without.
`outlet`	string	Outlet name or domain.
`author`	string	Author name as published.
`published_after`	date	Inclusive lower bound on publication time.
`published_before`	date	Inclusive upper bound on publication time. Must not precede `published_after`.
`ingested_after`	datetime	Inclusive lower bound on the time the article entered the index. See Polling.
`sort`	`published_at` \| `ingested_at` \| `relevance`	Sort field. Default `published_at`, or `relevance` for semantic search. See Sorting.
`order`	`asc` \| `desc`	Sort direction. Default `desc`.
`per_page`	integer	Results per page, 1–100. Default 25.
`cursor`	string	Pagination cursor from a previous response. See Pagination.

Enumerated values are case-insensitive.

Multiple values

country and language accept multiple values in any of these forms:

?country=NL&country=BE
?country[]=NL&country[]=BE
?country=NL,BE

Booleans

has_author accepts true, false, yes, no, 1 and 0. Omitting the parameter returns articles with and without authors.

Dates

published_after and published_before accept a date or a full timestamp. Both bounds are inclusive.

A date without a time covers the entire day. published_after=2026-03-01&published_before=2026-03-01 returns everything published on 1 March. A timestamp is applied exactly as given.

published_before=2026-03-01            # through 23:59:59 on 1 March
published_before=2026-03-01T09:00:00Z  # through 09:00 UTC on 1 March

ingested_after is applied exactly as given.

Search modes

search selects how q is interpreted. Each mode answers a different question.

Keyword

The default. q is matched as natural language: articles containing any of the terms are returned, with the closest matches ranked higher by the search engine before the page is sorted.

Boolean

search=boolean applies a small, explicit query grammar:

Syntax	Meaning	Example
`word word`	Every word must appear.	`overname bedrijf`
`"quoted phrase"`	The words must appear together, in order.	`"raad van bestuur"`
`-word`	The word must not appear.	`overname -voetbal`

curl -G 'https://api.presscloud.ai/v1/articles' \
  -H "Authorization: Bearer $PRESSCLOUD_API_KEY" \
  -d search=boolean \
  -d 'q="raad van bestuur" benoeming -interim'

Other punctuation is treated as a word separator: e-commerce matches the words e and commerce. There is no OR operator.

A query consisting only of exclusions returns 422 invalid_request.

Boolean search is a separate mode rather than the default so that existing queries containing - or " are unaffected.

Semantic

search=semantic matches q by meaning rather than exact wording. A query for overname also returns articles about the same subject whose headlines use fusie or koopt.

curl -G 'https://api.presscloud.ai/v1/articles' \
  -H "Authorization: Bearer $PRESSCLOUD_API_KEY" \
  -d search=semantic \
  -d q=overname \
  -d country=NL

Semantic search differs from the other modes in the following ways:

q is required and must be at least two characters.
search_in does not apply; combining the two returns 422 invalid_request.
Results are ordered by relevance by default, and each article includes a relevance score. sort=published_at or sort=ingested_at may be used instead; the relevance score is still included.
The search identifies up to 500 of the closest matches, then applies your other filters to those. Combining semantic search with a narrow filter can therefore return fewer results than the equivalent keyword or boolean search. Use keyword or boolean search when exhaustive coverage of a filtered subset is required.
New articles become available to semantic search a few hours after they enter the index. Keyword and boolean search cover an article as soon as it is indexed. For the most recent news, or when polling, use keyword or boolean search.
total_results is exact.

If semantic search is temporarily unavailable, the request returns 503 semantic_search_unavailable. Retry after a short delay, or repeat the request with another search mode.

Search scope

By default q is matched against the headline. search_in=title_body also matches the article text, which is usually what a monitoring query needs: most mentions of a brand or a name appear in the body rather than the headline.

curl -G 'https://api.presscloud.ai/v1/articles' \
  -H "Authorization: Bearer $PRESSCLOUD_API_KEY" \
  -d search=boolean \
  -d search_in=title_body \
  -d q=presscloud

search_in applies to keyword and boolean search.

Sorting

sort and order control the page order.

`sort`	Description
`published_at`	Publication time. The default for keyword and boolean search.
`ingested_at`	Time the article entered the index. Articles without an ingestion time are excluded.
`relevance`	Semantic relevance score. Only valid with `search=semantic`; the default for that mode.

order is desc by default for every field: newest first, or best match first.

sort=ingested_at with order=asc is the recommended way to poll for new articles. See Polling for new articles.

Plan coverage

Requests are validated against your plan. A request outside its coverage is rejected rather than partially fulfilled:

Condition	Code	Status
`country` includes a country not in your plan	`country_not_included`	`403`
`published_after` precedes your plan’s history start	`history_not_included`	`403`

When published_after is omitted, results begin at your plan’s history start.

Response

{
  "status": "ok",
  "total_results": 1482,
  "next_cursor": "eyJhcnRpY2xlX3B1Ymxpc2hlZF9hdCI6...",
  "articles": [ ... ]
}

Field	Description
`status`	`"ok"` on success. Errors return `"error"`; see Errors.
`total_results`	Number of matching articles. Capped at 10,000 for keyword and boolean search.
`total_results_is_estimate`	`true` when `total_results` reached its cap. Omitted otherwise.
`next_cursor`	Cursor for the next page, or `null` on the final page.
`articles`	Array of article objects.

RSS

The same query is available as an RSS 2.0 feed at GET /v1/articles.rss, with identical parameters. See RSS feed.