Why is my search returning no results?#

An empty search is almost always a filter problem, not a bug. The APITube News API returns HTTP 200 with status: "ok" and an empty results array when your query is valid but nothing matches it. The usual causes are filters that are too narrow (every filter you add is combined with AND), a keyword search that only looks at the headline, or an entity.id that matches nothing. Remove filters one at a time until results come back, then add them back to find the one that emptied the response.

{
    "status": "ok",
    "limit": 25,
    "page": 1,
    "has_next_pages": false,
    "results": []
}

A clean empty result like this means the request succeeded and simply found no articles — and because the News API only charges a request when at least one article is returned, an empty search does not cost a credit.

Is an empty result an error?#

No. An empty result is HTTP 200 with status: "ok" and results: [], which is a successful response that happened to match nothing. That is different from an error, which returns a 4xx status and an error code: a bad parameter returns 400, an authentication problem returns 401, and too many requests returns 429. If you are getting a status code other than 200, you are looking at an error, not an empty search — see understanding API error codes for the full map. So the first debugging step is to read the HTTP status: a 200 with an empty results array tells you the query ran and the filters excluded everything.

Why does adding more filters return nothing?#

Different filter parameters combine with AND, so each one you add narrows the result set, and a few specific filters together can reduce it to zero. For example title=earnings&language.code=ja&source.domain=bbc.com&published_at.start=NOW-1DAYS requires all four conditions at once — a Japanese-language BBC article with “earnings” in the headline from the last 24 hours — which may genuinely not exist.

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

To find the filter that empties your response, drop them one at a time and re-run the search until results appear. The filter you removed last is the one that excluded everything. For the rules on how filters stack, see how to combine multiple filters in one request.

Why doesn’t my keyword search find articles I know exist?#

The title parameter matches words in the article headline only, not the body. If your keyword appears in the article text but not the title, the article will not match. Two more rules narrow it further: when you pass several words, they are combined with AND (every word must be in the headline), and matching is by whole token, so ai does not match Jamaica and a partial word does not match a longer one.

curl "https://api.apitube.io/v1/news/everything?title=Tesla&api_key=YOUR_API_KEY"

If a multi-word title returns nothing, try fewer words, or wrap an exact phrase in quotes only when you really need it (title="climate change") — a quoted phrase is the strictest match of all. The title value must be 2 to 100 characters or the request fails with ER0007. When you are searching for coverage about a person or company rather than a literal headline word, filter by the entity instead — person.name, organization.name or entity.id — which matches the article wherever the entity is mentioned. See how to search news by title for the keyword rules.

Why does an entity or name filter come back empty?#

Name filters and ID filters fail differently, and knowing which you used explains the empty response. A name that APITube does not recognize fails loudly: an unknown person.name returns 400 with ER0216, and an unknown organization.name returns ER0220. So if a name filter returned a clean empty list instead of an error, the name resolved correctly and there is simply no recent coverage.

A numeric entity.id is the opposite — it is not checked against the directory, so an ID that matches no entity silently returns no articles rather than failing. If you filtered by entity.id and got nothing, confirm the ID is correct: read it from the entities array of a known article, or look it up in the directory. See how to find news mentioning a person or company for the difference between name and ID matching.

Why does my date filter return nothing?#

A date window that is too tight, or pointed at the future, excludes everything. published_at.start and published_at.end are the bounds, and a relative value like published_at.start=NOW-7DAYS means “the last seven days”. A common mistake is setting published_at.start to a time later than published_at.end, or to a moment in the future, which leaves no valid range:

curl "https://api.apitube.io/v1/news/everything?person.name=Tim Cook&published_at.start=NOW-30DAYS&api_key=YOUR_API_KEY"

Widen the window first (drop published_at.start entirely to confirm the rest of the query works), then tighten it. An unparseable date value is rejected with ER0104 for published_at.start rather than returning an empty list, so a clean empty response means the dates parsed but matched nothing.

How do I debug an empty search?#

Add debug=1 (or debug=true) to the request. The response then includes a user_input object that echoes exactly how the server parsed your parameters — with the API key removed — which quickly reveals a misspelled parameter name or a value that was not applied the way you expected.

curl "https://api.apitube.io/v1/news/everything?title=Tesla&debug=1&api_key=YOUR_API_KEY"

Then strip the query down to a single filter, confirm it returns articles, and add the others back one by one. To check how many articles a query matches before fetching any, use the count endpoint (/v1/news/count). One more thing to rule out: a test key or a free plan still returns matching articles, but the body is truncated to a preview — that is masked content, not an empty result, so check whether results is actually empty or just shortened.

Common Questions#

• Does an empty search cost a request or credit?
• My results have placeholder or shortened text — is that the same as no results?
• Why did a misspelled name return an error instead of an empty list?
• How do I check how many articles match before fetching them?

Does an empty search cost a request or credit?#

No. The News API only charges a request when at least one article is returned. A query that resolves to an empty results array does not decrement your request quota, so you can safely tune filters and re-run a search that returns nothing without spending credits.

My results have placeholder or shortened text — is that the same as no results?#

No. Shortened or preview body text means your articles matched and were returned, but the content was masked because you used a test key or a free plan. That is a content-masking behavior, not an empty search — results still contains articles. An empty search is specifically results: [] with no articles at all.

Why did a misspelled name return an error instead of an empty list?#

Because name filters validate against the entities APITube tracks. An unknown person.name returns ER0216 and an unknown organization.name returns ER0220, both HTTP 400, and the request stops rather than returning an empty list. This is intentional: it tells you the name itself is wrong instead of silently matching nothing. Fix the spelling, or switch to a numeric entity.id, which never triggers these errors.

How do I check how many articles match before fetching them?#

Send the same filters to /v1/news/count instead of /v1/news/everything. It returns the number of matching articles without downloading them, which is the fastest way to confirm whether a filter combination matches zero, a few, or millions of articles. See how to count matching articles for details.