How to search news in plain English#

Send your request as a sentence in the prompt parameter and the APITube News API turns it into real filters before it searches. The sentence must be 3 to 500 characters, and the parameters it produced come back in meta.prompt, so you can always see what actually ran.

curl -G "https://api.apitube.io/v1/news/everything" \
  --data-urlencode "prompt=Tesla and Elon Musk news in English for the last 10 days" \
  --data-urlencode "api_key=YOUR_API_KEY"

That one request is the equivalent of writing person.name=Elon Musk, organization.name=Tesla, language.code=en and published_at.start=NOW-10DAY yourself. You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key parameter, and prompt also works in a POST body.

What does the prompt parameter do?#

The prompt parameter is translated into the API’s ordinary parameters on the server, before the search runs. It is not a separate search engine and it is not a summary layer: after the translation, the request behaves exactly like a hand-written one, so sorting, pagination, field selection and export formats all still apply.

The translation can produce headline keywords and exact phrases (title), entity filters (person.name, organization.name, location.name, brand.name, event.name, disease.name, disaster.name, sport.name), taxonomy filters (category.id, topic.id, industry.id), source.domain, author.name, language.code, source.country.code, a date range, sentiment.overall.polarity, sort.by, sort.order, per_page, and the boolean flags is_breaking, has_image, has_video, is_paywall and is_long_read.

Two limits are worth knowing up front. Each filter takes at most 3 values, so a prompt naming eight companies will lose five of them. And broad sections are picked from the 17 top-level IPTC categories only — a narrow subject becomes a topic or a headline keyword instead, which keeps a wide question from silently turning into a narrow one.

How do I see which filters my prompt produced?#

Read meta.prompt in the response. Every JSON response to a request that used prompt carries it:

{
  "meta": {
    "prompt": {
      "text": "positive Tesla coverage from German publishers this month",
      "applied": {
        "organization.name": "Tesla",
        "source.country.code": "de",
        "sentiment.overall.polarity": "positive",
        "published_at.start": "NOW/MONTH"
      },
      "ignored": [
        { "field": "topic.id", "value": "electric vehicles", "reason": "not_found" }
      ],
      "cached": true
    }
  }
}

applied is the request that actually ran — this is the field to check first when results look wrong. ignored lists everything that was understood but not used, and cached tells you whether this wording had been parsed before.

Note that periods are stored as date math (NOW-10DAY, NOW/MONTH), not as calendar dates. The expression is resolved on every request, so a saved prompt keeps meaning “the last 10 days” next month too.

Why was part of my prompt ignored?#

Each entry in meta.prompt.ignored carries a reason:

• not_found — the name is not in APITube’s reference books. Entity names are not simply dropped: they fall back to a headline keyword, so the request still returns something sensible instead of a 400. To filter precisely, look the real name up first, as described in how to find news mentioning a person or company.
• explicit_param — you sent that parameter yourself and your value was kept. This is deliberate: an explicit parameter always beats the prompt, so you can pin language.code=de and let the prompt handle the topic.
• unsupported_on_endpoint — the endpoint does not accept that filter. This happens on /v1/news/raw, which only uses the dates, sort.order and per_page out of a prompt.
• invalid_date — the period could not be read as a date or as date math.
• title_too_long — the term did not fit the 100-character title budget and was dropped whole rather than cut in half.
• title_window_clamped — the prompt asked for a headline search over more than 31 days, so the start date was moved to the 31-day limit that applies to every title search.

Which endpoints accept a prompt?#

prompt works on /v1/news/everything, /v1/news/top-headlines, /v1/news/local, /v1/news/count, /v1/news/trends, the /v1/news/category, /v1/news/topic, /v1/news/industry and /v1/news/entity endpoints, and both real-time streams (/v1/news/stream and /v1/news/ws).

/v1/news/raw accepts it but applies only part of it. /v1/news/article, /v1/news/story, /v1/fact-check and the suggest endpoints ignore prompt completely — no translation runs there and nothing is charged.

The SSE stream applies the filters but returns no meta.prompt, because an SSE response has no JSON envelope. The WebSocket stream echoes the expanded filters in its subscribed acknowledgement frame instead.

How much does a prompt cost?#

Translating a prompt costs 2 points on top of the endpoint’s usual cost, and only when that exact wording has not been parsed before. Interpretations are cached for 24 hours against the normalized text, so Tesla NEWS and tesla news count as the same entry and the repeat is free. meta.prompt.cached tells you which one happened.

Which plans include the prompt parameter?#

prompt is available on Basic, Professional and Corporate. On the Free and Starter plans the request returns 403 with error code ER0706 and nothing is charged, because the plan is checked before the language model is called. Every filter a prompt would build — title, entity filters, categories, dates, sentiment — works on every plan; prompt is the paid convenience of having them written for you, and each new wording runs a language-model call on APITube’s side.

Plan	prompt
Free	No — 403 ER0706
Starter	No — 403 ER0706
Basic	Yes
Professional	Yes
Corporate	Yes

Your quota is checked at the same point, so an account out of points gets the usual 402 rather than paying for a translation. See compare APITube plans for the rest of the tier differences.

How is this different from Ask News and the MCP server?#

All three let you ask in plain language, but the language is interpreted in different places. The prompt parameter is interpreted inside the API and returns normal JSON. Ask News is a chat interface in the dashboard that calls the API for you and writes an answer. The MCP server lets an AI assistant build the filters on its side and call the API itself.

If you are writing code, prompt is usually the one you want: one HTTP request, no assistant in the loop, and a machine-readable record of how your sentence was read. The full parameter reference lives in the official News API parameter docs.

Common Questions#

• What do errors ER0706, ER0800, ER0801 and ER0802 mean?
• Can I mix a prompt with normal filters?
• Does the prompt search inside the article body?
• Can a prompt invent a category or entity that does not exist?
• Why did my prompt return no articles?

What do errors ER0706, ER0800, ER0801 and ER0802 mean?#

ER0706 is HTTP 403 and means the plan does not include prompt — Free and Starter keys get it, and nothing is charged. The same number is also used by the Fact Check endpoint and by the boolean query parser, so match on the HTTP status and message, not on the code alone. ER0800 is HTTP 400 and means the prompt is shorter than 3 or longer than 500 characters. ER0801 is HTTP 502 and means the translation service was unavailable — nothing is charged, so retry. ER0802 is HTTP 400 and means nothing usable came out of the prompt: either no filter was found in the sentence, or everything it produced was overridden by your explicit parameters or unsupported on that endpoint. There is no silent fallback, which is intentional — a failed translation should not look like an answer.

Can I mix a prompt with normal filters?#

Yes, and the mix is predictable: any parameter you send explicitly wins, and the prompt’s version of it is reported in meta.prompt.ignored with reason: explicit_param. This is the recommended pattern for production code — pin the parts that must be exact, such as language.code or source.domain, and let the prompt cover the topic.

Does the prompt search inside the article body?#

No. APITube’s search covers headlines, not article bodies, and a prompt cannot change that. Wording that no structured field covers becomes a title search — up to 3 terms, 100 characters in total — exactly as if you had passed those keywords yourself.

Can a prompt invent a category or entity that does not exist?#

No. The language model returns names, never identifiers; IDs are looked up afterwards against APITube’s own reference books. Entity names are matched exactly, ignoring case, so a near miss is not accepted — the entity book has no generic “Earthquake”, only specific ones like “2013 Aceh earthquake”, and picking one of those would quietly replace a broad question with a single event.

Why did my prompt return no articles?#

Check meta.prompt.applied before anything else. The most common causes are a filter combination that is simply too narrow, an entity that fell back to a headline keyword after not_found, or a date range you did not intend. Remove one filter at a time from the applied set by rewriting the sentence, or send those parameters by hand once you know which one is emptying the result.