How to get all articles covering the same story#

To find every article that covers the same story as one you already have, call the /v1/news/story/:id endpoint with that article’s ID in the path. The endpoint reads the source article’s title, pulls out its meaningful keywords, and returns other articles whose titles share those keywords — ranked so the closest matches come first. This finds related coverage of article 1234567:

curl "https://api.apitube.io/v1/news/story/1234567?api_key=YOUR_API_KEY"

You can pass the key as the api_key query parameter or as an X-API-Key header. The ID you put in the path is the same id value returned by every search and retrieval result, so the typical flow is: run a search, take the id of one article, then ask the story endpoint for the rest of the coverage around it.

How does APITube decide which articles belong to the same story?#

The story endpoint does not rely on a pre-built cluster ID. Instead, it works from the source article’s headline: it tokenizes the title, drops stopwords, and keeps the remaining keywords (each at least two characters). It then searches for other articles whose titles contain those keywords and ranks them by how many keywords overlap — an article matching more of the source headline’s keywords ranks above one matching fewer. The source article itself is always excluded from the results, so you only get the other coverage.

Because matching is keyword-based, the most reliable inputs are articles with a clear, specific headline. If the source title has no usable keywords after stopwords are removed, the endpoint returns ER0240 (HTTP 404) rather than guessing.

How to narrow a story to one language, date range or source#

The story endpoint accepts the same filters as a normal search, so you can scope the related coverage. Add any standard filter alongside the path ID — for example, restrict it to English coverage and to one source:

curl "https://api.apitube.io/v1/news/story/1234567?language.code=en&source.domain=reuters.com&api_key=YOUR_API_KEY"

You can also limit by date with published_at.start and published_at.end (see How to filter news by date range), or by any other filter from the Searching & Filtering News section. Results are paginated: per_page defaults to 100 and accepts up to 250 (a higher value returns ER0171), and page walks through the matches.

What does the story endpoint return?#

The response is the standard JSON envelope: a results array of full article objects plus paging fields and a request_id:

{
  "status": "ok",
  "limit": 100,
  "page": 1,
  "has_next_pages": false,
  "results": [
    {
      "id": 7654321,
      "href": "https://example.com/same-story-different-source",
      "title": "...",
      "published_at": "2026-06-20T08:00:00.000Z",
      "language": "en",
      "source": { "domain": "example.com" }
    }
  ],
  "request_id": "c2e6a48b-1d59-4f37-8b0a-9c3e7d1f2a56"
}

Each object carries the usual article fields — id, href, published_at, title, body, body_html, language, author, image, categories, topics, industries, entities and source — the same shape you get from fetching an article by ID. To trim the payload, add fl with a comma-separated list of field paths, for example fl=id,title,href,published_at.

How much does a story request cost?#

Each /v1/news/story/:id call costs 1 credit, and you are only charged when the endpoint returns at least one related article. If no other coverage matches the source headline, no credit is spent. The endpoint accepts both GET (ID in the path) and POST (same path, filters in a JSON body); the two are equivalent.

Common Questions#

• Why did I get “Article not found”?
• Why are the article bodies truncated?
• What errors can the story endpoint return?
• Is the source article included in the results?

Why did I get “Article not found”?#

A 404 with ER0235 means the ID you passed in the path does not match any article in the index — double-check that you copied the id from a recent search or retrieval result. A separate 404 with ER0240 means the article was found, but its title had no usable keywords left after stopwords were removed, so there was nothing to match a story on.

Why are the article bodies truncated?#

Article content is masked on Free-plan keys and on test keys (those starting with api_test_). Both return a shortened body with an upgrade marker instead of the full text, so you can preview the response shape without full content. Use a live key on a paid plan to receive the complete body and body_html.

What errors can the story endpoint return?#

The common ones are: ER0231 (HTTP 400) when no article ID is supplied, ER0235 (HTTP 404) when the ID matches no article, ER0240 (HTTP 404) when the title yields no keywords, ER0201/ER0202 (HTTP 401) when the API key is missing or invalid, and ER0176 (HTTP 402) when your account has no credits left. Every error response includes the request_id for tracing.

Is the source article included in the results?#

No. The endpoint always excludes the article whose ID you passed, so results contains only the other articles covering the same story. To read the source article’s own full content, fetch it separately with /v1/news/article.