Natural Language Search

Describe the news you want in the prompt parameter. The API turns your words into filters and returns matching articles. Check meta.prompt to see which filters it used.

prompt is available on Basic and above. Free and Starter return 403 ER0706. Translating a prompt costs 2 points. Repeating the same prompt within 24 hours does not add a translation charge.

curl "https://api.apitube.io/v1/news/everything?prompt=Tesla%20and%20Elon%20Musk%20news%20in%20English%20for%20the%20last%2010%20days&api_key=YOUR_API_KEY"

That single request produces the same result as writing the filters yourself:

person.name=Elon Musk
organization.name=Tesla
language.code=en
published_at.start=NOW-10DAY

See Parameters for the prompt reference. Read below for supported filters, response fields and limits.

How it differs from the MCP server and Ask News

Choose how you want to ask for news:

How you search	Where the language is interpreted	What you get back
prompt parameter	Inside the API, before the search runs	The normal JSON response, plus meta.prompt
MCP Server	In the AI assistant, which then calls the API with filters	Whatever your assistant does with the articles
Ask News (dashboard)	In the chat interface, which calls the API for you	A written answer with sources

Use prompt to search from your application in one HTTP request. You do not need an AI assistant, and the response includes the filters used.

What the translation can produce

A prompt can use only existing API filters and known names or IDs.

Text search. If your words do not match a filter such as a person, category or source, the API searches for them in headlines. It puts up to 3 terms in title, with a total limit of 100 characters. Text in quotes stays an exact phrase. The prompt cannot search article bodies.

Entities. People become person.name, places location.name, companies and organizations organization.name, product brands brand.name, named events event.name, diseases disease.name, natural disasters disaster.name, sports sport.name. Up to 3 values each.

Categories and topics. Broad subjects use category.id from the 17 top-level IPTC categories, such as politics and government, economy, business and finance, sport and health. More specific subjects use topic.id or industry.id.

Publishers and journalists. Publisher domains become source.domain; journalist names become author.name.

Language and geography. Article language becomes language.code, publisher country source.country.code.

Time. Periods use relative expressions in published_at.start and published_at.end. For example, "the last 10 days" becomes NOW-10DAY. This range updates with each request.

Other filters. Tone becomes sentiment.overall.polarity, sorting uses sort.by and sort.order, and the number of articles becomes per_page. Yes-or-no conditions use is_breaking, has_image, has_video, is_paywall and is_long_read: 1 requires the condition and 0 excludes it.

How names become identifiers

The API uses known names to select entity, category, topic and industry IDs. Check meta.prompt to see the values applied to your request.

Entity names must match a known name, ignoring case. For example, a general request for earthquakes will not automatically select a specific event such as the 2013 Aceh earthquake.

If an entity name is unknown, the API searches for it in headlines and lists the unused entity filter in meta.prompt.ignored with reason: not_found. Unknown domains, topics and other non-entity values are left out and reported in the same way. The request can still return results.

For topics and industries, the API uses an exact name match when available. Otherwise, it selects the shortest matching name.

Reading meta.prompt

Every JSON response to a request that used prompt carries the interpretation:

{
  "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
    }
  }
}

Field	Meaning
text	Your prompt, trimmed, exactly as it was parsed.
applied	The parameters that were added to the request. This is the request that actually ran.
ignored	Values that were understood but not used, each with a field, a value and a reason.
cached	true when this wording had already been parsed, meaning no parse fee was charged.

Use the fields in meta.prompt to check how the API understood your request.

Why a value was ignored

reason	What happened	What to do
not_found	The name is not in the API's list of known values. Unknown entity names are searched in headlines instead.	Find the name with Suggest and pass its ID.
explicit_param	You sent that parameter yourself; your value was kept.	No action needed. Values you send directly take priority.
unsupported_on_endpoint	The endpoint does not accept that filter.	Move the request to /v1/news/everything.
invalid_date	The period could not be read as a date or as date math.	Pass published_at.start / published_at.end yourself.
title_too_long	The term would exceed the 100-character limit for title, so the whole term was left out.	Shorten the prompt.
title_window_clamped	The prompt produced a headline search plus a range wider than 31 days, so published_at.start was moved to the 31-day limit.	Expected — see Search window limit.

Combining a prompt with ordinary parameters

Parameters you send directly take priority over filters from prompt. Set exact requirements, such as language, yourself and describe the rest in the prompt.

# The prompt asks for English, but language.code=de wins
curl "https://api.apitube.io/v1/news/everything?prompt=Tesla%20news%20in%20English&language.code=de&api_key=YOUR_API_KEY"

The overridden value shows up as {"field": "language.code", "value": "en", "reason": "explicit_param"}.

The filters from your prompt work like parameters you set yourself. You can still use sorting, pagination, field selection, faceting and any export format.

Endpoint behaviour

Endpoint	Behaviour
/v1/news/everything, /v1/news/top-headlines, /v1/news/local, /v1/news/count, /v1/news/trends	Full support, meta.prompt in the response.
/v1/news/category, /v1/news/topic, /v1/news/industry, /v1/news/entity	Full support. The URL path selects the category, topic, industry or entity. The prompt adds other filters.
/v1/news/raw	Accepted, but this endpoint only understands published_at.start, published_at.end, sort.order and per_page. Everything else is reported with reason: unsupported_on_endpoint.
/v1/news/stream	The prompt is validated and its filters are applied to the stream, but SSE has no JSON response, so there is no meta.prompt to read.
/v1/news/ws	Supported. The subscribed message shows the filters used.
/v1/news/article, /v1/news/story, /v1/fact-check, /v1/suggest/*	prompt is ignored entirely. No translation runs and nothing is charged.

prompt works both as a query-string parameter and inside a POST body, on every endpoint above.

Cost, caching and quota

A new prompt translation costs 2 points in addition to the endpoint's cost. Repeating the same prompt within 24 hours uses the cached translation for free. Case and extra spaces do not matter: Tesla NEWS and tesla news count as the same prompt. Check meta.prompt.cached to see whether you were charged for a translation.

Repeated prompts still use current date ranges and current filter values. For example, NOW-10DAY always means the 10 days before the request.

If your quota is exhausted, the API returns 402 ER0176 without a translation charge. Reaching a pay-as-you-go spending limit returns 402 ER0177. Failed translations are also free.

Plan availability

prompt is available on Basic and above. On Free and Starter the request fails with 403 ER0706 before the translation runs, so nothing is charged. Every other way of searching — the regular filters, the boolean query language, all endpoints — works on every plan.

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

Errors

Code	HTTP	When
ER0706	403	The plan does not include prompt (Free and Starter). Nothing is charged.
ER0800	400	The prompt is shorter than 3 or longer than 500 characters.
ER0801	502	The translation service is unavailable. Nothing is charged; retry.
ER0802	400	Nothing usable came out of the prompt — either no filter was found in it, or everything it produced was overridden or unsupported.

If the API cannot translate your prompt, it returns an error. It will not return unfiltered articles as an answer.

On /v1/news/ws, these errors arrive in an error message followed by close code 4001. Full list: Prompt Errors.

Writing prompts that work

• Use full names. "Elon Musk" matches a known person; "the Tesla guy" is searched as a headline keyword.
• Keep each request focused. The API keeps at most 3 values per field. If you list eight companies, only the first three are used.
• Include a date range in your prompt. For example, "in the last two weeks" or "since the start of the month". Without a date range, the API applies no date filter unless the prompt searches headlines. Headline searches cover at most 31 days.
• Check meta.prompt.applied the first time. It is the fastest way to see whether the sentence was read the way you meant it.
• Set exact requirements as parameters. Send language.code or source.domain directly when you need a specific language or publisher. Use the prompt to describe the subject.

Next steps

• Parameter reference: prompt
• Find an entity's ID: Suggest
• Search with an AI assistant: MCP Server