Frequently asked questions#

This page gives the short answer to the questions people ask most often when they start with the APITube News API — the base URL, how to authenticate, what a request costs, how results are ordered and limited, and how to read an error. Each answer links to the full guide when there is more to know.

What is the base URL and main endpoint?#

The News API lives at https://api.apitube.io, and the primary search endpoint is /v1/news/everything. It accepts both GET (parameters in the query string) and POST (parameters in the JSON body), so a minimal call looks like this:

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

Other endpoints sit under the same /v1/ prefix — for example /v1/news/count to count matches and /v1/balance to read your credit balance.

How do I authenticate my requests?#

Send your API key in the X-API-Key request header, or as the api_key query parameter (an Authorization: Bearer <key> header also works). If no key is sent the API returns 401 with code ER0201; an invalid or revoked key returns ER0202, and an expired key returns ER0230. If you are getting 401 responses, see how to fix authentication (401) errors.

What counts as one request, and when am I charged?#

A successful search costs one request (one credit), and you are charged only when the response returns at least one article. A query that matches nothing returns an empty list and does not decrement your quota, so you can tune filters and re-run a search that comes back empty without spending credits. To see how many articles a filter combination matches before you fetch them, send the same parameters to the count endpoint, and to read your remaining credits call the balance endpoint.

Why is article content shortened or showing placeholder text?#

You are using a test key or a free plan, both of which return matching articles but truncate the body to a preview. A test key marks the cut text [Test mode — use a live key for full content] and a free plan marks it [Upgrade subscription plan]. This is content masking, not an error and not an empty result — the articles matched and were returned. Use a live key on a paid plan for full bodies. See why results are masked or placeholder text.

What is the default sort order, and how many results can I get per page?#

By default the News API sorts by published_at in descending order, so the newest articles come first. You can change this with sort.by and sort.order — see how to sort news by relevance, date or quality. Page size is controlled by per_page, which defaults to 100 and has a maximum of 250 — asking for more than 250 returns a 400 error (ER0171). Walk through large result sets with the page parameter, as described in how to paginate through results.

Why does my search return no results?#

An empty search is HTTP 200 with status: "ok" and an empty results array — a successful request that matched nothing, not an error. The usual cause is filters that are too narrow: different filters combine with AND, so each one you add can only shrink the result set. Remove filters one at a time until results come back to find the one that emptied the response. See why is my search returning no results for the full checklist.

What are the rate limits?#

The per-minute ceiling is 50 requests on paid plans, 10 on the free plan, 15 on test keys, and 10 on fact-check. Exceeding it returns 429 with code ER0203, whose message tells you how long to wait; repeated violations trigger a temporary ban (ER0204) after 30 offenses. Add a short delay and retry — see how to fix rate-limit (429) errors.

What export formats are available?#

A search can return more than JSON. Add the export parameter to get the same results as csv, tsv, xml, rss, xlsx, parquet or jsonl — for example ?export=csv. The default, with no export parameter, is JSON.

Common Questions#

• How do I read an API error?
• Does the API return cached data?

How do I read an API error?#

Every failed request returns the same JSON envelope: a top-level status of not_ok, a request_id, and an errors array. Read errors[0].code (an ERxxxx value) together with errors[0].message — for a 400, the message names the exact parameter at fault. The same request_id is also returned as the X-Request-ID header; quote it when you contact support. The full map of statuses and codes is in understanding API error codes and HTTP responses.

Does the API return cached data?#

No. Responses are sent with Cache-Control: no-store, because news changes by the minute and a stale cached copy would show outdated articles. If the same request returns different results on a later call, that is fresh data, not a caching bug.