List articles

GET

/articles

const url = 'https://api.presscloud.ai/v1/articles?q=overname&search=keyword&search_in=title&country=NL&country=BE&language=nl&has_author=true&published_after=2026-01-01&published_before=2026-03-01&ingested_after=2026-08-20T07%3A44%3A12Z&sort=published_at&order=asc&per_page=25';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://api.presscloud.ai/v1/articles?q=overname&search=keyword&search_in=title&country=NL&country=BE&language=nl&has_author=true&published_after=2026-01-01&published_before=2026-03-01&ingested_after=2026-08-20T07%3A44%3A12Z&sort=published_at&order=asc&per_page=25' \
  --header 'Authorization: Bearer <token>'

Returns articles matching the filters, most recently published first. Every parameter is optional.

Authorizations

bearerAuth

Parameters

Query Parameters

string

<= 191 characters

The search term. Required, and at least 2 characters, when search=semantic.

Example

overname

search

string

default: keyword

Allowed values: keyword boolean semantic

How q is matched.

keyword (default) matches as natural language. boolean applies an explicit grammar: every word required, "quoted phrases", and a leading - excludes. semantic matches by meaning: up to 500 of the closest matches are identified, the remaining filters are applied to those, and results are ordered by relevance with a relevance field on each article. Combining semantic search with a narrow filter may return fewer results than the equivalent keyword or boolean search.

search_in

string

default: title

Allowed values: title title_body

Whether q is matched against the headline only (title, default) or the headline and article text (title_body). Applies to keyword and boolean search; combining it with search=semantic returns 422.

country

Array<string>

Allowed values: NL BE LU

Country of the publishing outlet. Repeatable, and a comma-separated list is also accepted (country=NL,BE).

Example

[
  "NL",
  "BE"
]

language

Array<string>

Allowed values: nl fr de lb en

Repeatable, and a comma-separated list is also accepted.

Example

[
  "nl"
]

has_author

boolean

Restrict to articles that carry a by-line. Accepts true, false, yes, no, 1 and 0. Omitting the parameter means either.

Example

true

outlet

string

<= 191 characters

Matches the outlet name or domain.

author

string

<= 191 characters

Matches the author name as the outlet published it.

published_after

string format: date

Inclusive lower bound. With no value, the plan’s own history window applies.

Example

2026-01-01

published_before

string format: date

Inclusive upper bound, covering the whole day named. Must be on or after published_after. A value carrying its own time is honoured exactly.

Example

2026-03-01

ingested_after

string format: date-time

Inclusive lower bound on the time the article entered the index. Use with sort=ingested_at&order=asc to poll for new articles without missing late arrivals.

Example

2026-08-20T07:44:12Z

sort

string

Allowed values: published_at ingested_at relevance

Sort field. Defaults to published_at, or relevance for semantic search. relevance is only valid with search=semantic. ingested_at excludes articles without an ingestion time.

order

string

default: desc

Allowed values: asc desc

Sort direction.

per_page

integer

default: 25 >= 1 <= 100

Articles per page.

cursor

string

<= 255 characters

The next_cursor value from a previous response. All other parameters must remain identical between pages. An invalid cursor returns 422.

Responses

200

A page of articles.

application/json

object

status

required

string

Allowed value: ok

total_results

required

Number of matching articles. Capped at 10,000 for keyword and boolean search; exact for semantic search.

integer

total_results_is_estimate

true when total_results reached its cap. Omitted otherwise.

boolean

next_cursor

required

Cursor for the next page, or null on the final page.

string | null

articles

required

Array<object>

An article. The full article text is not included.

object

required

Opaque, stable identifier. Use it to deduplicate across requests.

string

title

required

string

url

required

string format: uri

snippet

required

The first 200 characters of the body, HTML stripped, no ellipsis. Null when no body was captured.

string | null

published_at

required

Publication time. ISO 8601, UTC.

string | null format: date-time

ingested_at

required

Time the article entered the index. ISO 8601, UTC. Typically minutes to a few hours after published_at.

string | null format: date-time

authors

required

Empty when the outlet published no by-line. Roughly 9% of articles carry one.

Array<object>

object

required

string

name

required

string

outlet

required

object

name

required

string | null

domain

required

string | null

language

required

string

Allowed values: nl fr de lb en

country

required

One of:

string
null

Country of the publishing outlet, not of the article’s subject.

string

Allowed values: NL BE LU

relevance

Relevance score between 0 and 1, rounded to four decimals. Included only in semantic search results, which are ordered by it. Omitted from keyword search results.

number

Example

{
  "status": "ok",
  "total_results_is_estimate": true,
  "articles": [
    {
      "id": "art_5c31b0",
      "published_at": "2026-08-20T07:42:00Z",
      "ingested_at": "2026-08-20T07:44:12Z",
      "authors": [
        {
          "id": "aut_8f21c4",
          "name": "Joris de Vries"
        }
      ],
      "outlet": {
        "name": "Example Zakelijk",
        "domain": "example.nl"
      },
      "language": "nl",
      "country": "NL",
      "relevance": 0.7314
    }
  ]
}

Headers

X-RateLimit-Limit

integer

Requests per minute allowed by the plan. Present on every response.

X-RateLimit-Remaining

integer

Requests left in the current minute. Present on every response.

X-Quota-Limit

integer

Requests allowed this month. Present when the plan has a quota.

X-Quota-Remaining

integer

Requests left this month.

X-Quota-Reset

integer

Unix timestamp at which the quota resets — the start of next month.

X-Quota-Period

string

The period the quota counters describe.

401

missing_token or invalid_token.

application/json

Error response. Use code for error handling; message is descriptive and may change.

object

status

required

string

Allowed value: error

code

required

string

Allowed values: missing_token invalid_token too_many_failed_attempts country_not_included history_not_included invalid_request rate_limit_exceeded quota_exceeded semantic_search_unavailable

message

required

string

errors

Per-parameter validation messages. Only present on invalid_request.

object

key

additional properties

Array<string>

Example

{
  "status": "error",
  "code": "invalid_token",
  "message": "This API key is not valid."
}

403

A filter outside the plan: country_not_included or history_not_included.

application/json

Error response. Use code for error handling; message is descriptive and may change.

object

status

required

string

Allowed value: error

code

required

string

Allowed values: missing_token invalid_token too_many_failed_attempts country_not_included history_not_included invalid_request rate_limit_exceeded quota_exceeded semantic_search_unavailable

message

required

string

errors

Per-parameter validation messages. Only present on invalid_request.

object

key

additional properties

Array<string>

Example

{
  "status": "error",
  "code": "country_not_included",
  "message": "This plan does not include coverage for BE."
}

422

invalid_request. Carries per-parameter messages.

application/json

Error response. Use code for error handling; message is descriptive and may change.

object

status

required

string

Allowed value: error

code

required

string

Allowed values: missing_token invalid_token too_many_failed_attempts country_not_included history_not_included invalid_request rate_limit_exceeded quota_exceeded semantic_search_unavailable

message

required

string

errors

Per-parameter validation messages. Only present on invalid_request.

object

key

additional properties

Array<string>

Example

{
  "status": "error",
  "code": "invalid_request",
  "message": "One or more query parameters are not valid.",
  "errors": {
    "per_page": [
      "The per page field must not be greater than 100."
    ]
  }
}

429

rate_limit_exceeded, quota_exceeded or too_many_failed_attempts. Distinguish by code.

application/json

Error response. Use code for error handling; message is descriptive and may change.

object

status

required

string

Allowed value: error

code

required

string

Allowed values: missing_token invalid_token too_many_failed_attempts country_not_included history_not_included invalid_request rate_limit_exceeded quota_exceeded semantic_search_unavailable

message

required

string

errors

Per-parameter validation messages. Only present on invalid_request.

object

key

additional properties

Array<string>

Example

{
  "status": "error",
  "code": "rate_limit_exceeded",
  "message": "Too many requests. Slow down and retry after the interval in the Retry-After header."
}

Headers

Retry-After

integer

Seconds to wait before retrying.

503

semantic_search_unavailable. Semantic search is temporarily unavailable. Retry after a short delay, or repeat the request with search=keyword.

application/json

Error response. Use code for error handling; message is descriptive and may change.

object

status

required

string

Allowed value: error

code

required

string

Allowed values: missing_token invalid_token too_many_failed_attempts country_not_included history_not_included invalid_request rate_limit_exceeded quota_exceeded semantic_search_unavailable

message

required

string

errors

Per-parameter validation messages. Only present on invalid_request.

object

key

additional properties

Array<string>

Example

{
  "status": "error",
  "code": "semantic_search_unavailable",
  "message": "Semantic search is temporarily unavailable. Retry shortly, or repeat the request with search=keyword."
}