How to paginate through News API results#

To page through results in the APITube News API, use two parameters: per_page sets how many articles each request returns (default 100, maximum 250), and page selects which slice you get (default 1). Each response tells you whether more pages exist through the has_next_pages flag and a ready-to-use next_page URL, so you keep requesting pages until has_next_pages is false.

curl "https://api.apitube.io/v1/news/everything?per_page=50&page=1&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter, and both parameters work the same way on a GET query string or in a POST JSON body.

Which parameters control pagination?#

Pagination on /v1/news/everything is offset-based and driven by exactly two parameters:

• per_page — the number of articles in one response. The default is 100 and the hard maximum is 250. Asking for more than 250 returns a 400 error with code ER0171 (“Limit is out of range.”), so cap your page size at 250.
• page — which page of results to return, starting at 1. The API skips (page - 1) × per_page articles before returning the next batch, so page=3 with per_page=50 starts at the 101st matching article. On the Free plan, paging stops after the first 5 pages: any page above 5 returns 400 ER0173 (“Free plan is limited to the first 5 pages.”). Upgrade to a paid plan to page further.

Both parameters must be whole numbers. A non-integer per_page returns 400 ER0170 (“‘Per page’ is not a number.”), and a non-integer page returns 400 ER0172 (“Page is not a number.”).

How do you move to the next page?#

Read the pagination fields the API returns alongside results. Every search response includes:

• page — the page you just received.
• limit — the per_page value in effect.
• has_next_pages — true while another page may exist.
• next_page — a complete URL for the following page (empty when there is none).
• has_previous_page and previous_page — the same, going backwards.

The simplest loop is to request page 1, then keep following next_page until has_next_pages is false. Because has_next_pages is set whenever the current batch comes back full (its length equals per_page), a final page that happens to be exactly full will report has_next_pages: true, and the next request will return an empty results array. Treat an empty results list as the real end of the data, even if the previous page hinted there was more.

How do you get the total number of matches?#

The /v1/news/everything response does not include a total count — it only tells you whether the next page exists. When you need the full number of matching articles up front (for example, to show “1 of N” or to decide how many pages to fetch), send the same filters to the count endpoint, /v1/news/count. It runs the identical query and returns a single count value for one request, without downloading any article bodies.

curl "https://api.apitube.io/v1/news/count?title=tesla&language.code=en&api_key=YOUR_API_KEY"

Common Questions#

What is the maximum page size?#

The maximum per_page is 250 articles. Requests above that limit are rejected with 400 ER0171 instead of being silently capped, so set per_page to 250 or lower. If you leave it out, the API uses 100 per page.

Why do articles shift between pages?#

Pagination returns a slice of a sorted list, and the default sort is published_at in descending order (newest first). If you paginate a live search while new articles are being indexed, freshly added items can push everything down by one position, so an article from page 1 may reappear on page 2. To keep the order stable across pages, fix the ordering with the same sort.by and sort.order on every request, and narrow the window with a published_at.end boundary so the result set stops growing while you read it.

Which errors can pagination return?#

The pagination errors are all 400 responses: ER0170 when per_page is not a number, ER0171 when per_page exceeds 250, ER0172 when page is not a number, and ER0173 when a Free-plan key requests a page beyond 5. Send integers within range — and stay within the first 5 pages on the Free plan — and you will not hit any of them. For the full parameter reference, see the official News API parameters documentation.