Pagination

Results are paginated with a cursor. Each response includes next_cursor; pass it as the cursor parameter to retrieve the following page. On the final page, next_cursor is null.

curl -G 'https://api.presscloud.ai/v1/articles' \
  -H "Authorization: Bearer $PRESSCLOUD_API_KEY" \
  -d country=NL \
  -d per_page=100 \
  -d cursor=eyJhcnRpY2xlX3B1Ymxpc2hlZF9hdCI6...

per_page accepts 1 to 100 and defaults to 25.

Retrieving all results

Keep all other parameters identical between pages.

$cursor = null;

do {
    $response = Http::withToken(config('services.presscloud_news.key'))
        ->baseUrl('https://api.presscloud.ai/v1')
        ->get('/articles', array_filter([
            'country' => 'NL',
            'per_page' => 100,
            'cursor' => $cursor,
        ]))
        ->throw();

    foreach ($response->json('articles') as $article) {
        // ...
    }

    $cursor = $response->json('next_cursor');
} while ($cursor !== null);

cursor = None

while True:
    params = {"country": "NL", "per_page": 100}
    if cursor:
        params["cursor"] = cursor

    response = requests.get(
        "https://api.presscloud.ai/v1/articles",
        headers={"Authorization": f"Bearer {api_key}"},
        params=params,
    )
    response.raise_for_status()
    payload = response.json()

    for article in payload["articles"]:
        ...

    cursor = payload["next_cursor"]
    if cursor is None:
        break

An invalid or malformed cursor returns 422 invalid_request.

Behaviour

Cursor pagination provides consistent performance at any depth. It does not support jumping to an arbitrary page; retain cursors if your application needs to revisit earlier pages.

New articles are indexed continuously. A pagination sequence returns the result set as it stood when the sequence began.

total_results describes the full result set, not the current page. Iterate until next_cursor is null rather than calculating page counts from it; for keyword requests the value is capped at 10,000.

Polling for new articles

Articles enter the index minutes to several hours after publication, and the delay varies by source. An article can therefore appear in the index carrying a published_at that is already older than your last poll. Polling on published_after misses these articles permanently.

Poll on ingestion time instead. Record the most recent ingested_at you have processed, and on the next request pass it as ingested_after with sort=ingested_at&order=asc:

curl -G 'https://api.presscloud.ai/v1/articles' \
  -H "Authorization: Bearer $PRESSCLOUD_API_KEY" \
  -d country=NL \
  -d ingested_after=2026-08-20T07:44:12Z \
  -d sort=ingested_at \
  -d order=asc \
  -d per_page=100

Page through the results until next_cursor is null, then store the last ingested_at for the following poll. Deduplicate on id.

ingested_after is inclusive, so the final article of one poll is the first article of the next.

Poll with keyword or boolean search. Articles become available to semantic search a few hours after they are indexed, so a semantic poll lags behind the index.

Semantic search

Semantic search paginates identically. The result set contains at most 500 articles and remains stable for approximately five minutes, so pagination sequences should be completed within that window.