What is a story cluster (story vs article)?#

A story in the APITube News API is a cluster of articles that cover the same real-world event across different sources, while an article is one single news item from one source. One event usually produces many articles — a dozen outlets reporting the same election result — and the story is the group that ties them together. The article is the unit you read; the story is the spread of coverage around it.

APITube does not stamp a fixed story ID onto each article. Instead it builds a story on demand from a seed article: you pass one article’s id to the /v1/news/story/:id endpoint, and it returns the other articles whose headlines share the same keywords, ranked so the closest matches come first. That means any article can act as the seed for its own story cluster.

What is the difference between a story and an article?#

An article is a single, standalone record. It has a unique id, one source, one URL, and its own full set of fields — title, body, publication date, language, entities, sentiment and more. When you fetch or search articles, each result is one article.

A story is a relationship between articles, not a separate object you store. It is the set of articles that report the same event. Because coverage of a real event is scattered across publishers, the story lets you move from “here is one report” to “here is everyone’s report of this event.” So the two answer different questions: an article answers “what does this one piece say?”, and a story answers “who else covered this, and how?”

How does APITube build a story cluster?#

APITube builds a story from the seed article’s headline, at query time. It reads the seed article’s title, tokenizes it, drops stopwords, and keeps the remaining keywords (each at least two characters). It then finds other articles whose titles contain those keywords and ranks them by how many keywords overlap — an article matching more of the seed headline ranks above one matching fewer. The seed article itself is always excluded, so you get only the other coverage.

Because there is no pre-built cluster ID, the seed article is what defines the story. You call the endpoint with the seed’s id in the path:

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

If the seed title has no usable keywords left after stopwords are removed, the endpoint returns ER0240 rather than guessing. For the full request, filtering and pagination options, see how to get all articles covering the same story.

How is a story different from a duplicate article?#

A story and a duplicate are not the same thing. A story groups different articles — different sources, different wording — that happen to cover the same event. A duplicate is a near-identical copy of the same article, usually syndicated or reposted across sites with the same text.

APITube flags duplicates at the article level, so you control them with the is_duplicate filter (0 or 1). Use is_duplicate=0 to thin flagged reprints from a feed:

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

In short: use is_duplicate to thin flagged reprints from a stream — it is an approximate flag, not exhaustive reprint detection, so is_duplicate=0 reduces reprints without guaranteeing every copy is removed — and use the story endpoint to gather the varied coverage of one event. See how to exclude paywalled or duplicate articles for the dedup filter.

When should I use a story instead of a single article?#

Use a single article when you want one item’s full content — fetch it by id. Use a story when you want the whole picture of one event: every source’s version, so you can compare how outlets frame it, trace it back toward the original report, or gauge how widely it spread. Because a story is seeded from any article id, the typical flow is: run a search, take the id of one result, then ask the story endpoint for the rest of the coverage around it.

Common Questions#

• Does every article belong to a stored story?
• Is there a story ID I can save and reuse?
• How much does a story request cost?
• What happens if the story returns no other articles?

Does every article belong to a stored story?#

No. APITube does not assign each article to a fixed, pre-built story cluster. A story is computed at query time from a seed article you choose, so any article can be the starting point of its own story. As long as the seed article’s title has usable keywords, you can ask for the coverage around it.

Is there a story ID I can save and reuse?#

There is no separate story ID to store — clusters are built on demand from a seed article’s id. To reproduce a story later, save the seed article’s id and call /v1/news/story/:id again. The set of related articles can change over time as new coverage is published and matched against the seed headline.

How much does a story request cost?#

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

What happens if the story returns no other articles?#

If no other article’s headline overlaps the seed article’s keywords, you get an empty result set — that is a normal outcome, not an error, and no credit is charged. A 404 with ER0240 is different: it means the seed article was found, but its title produced no usable keywords to match on. A 404 with ER0235 means the id you passed does not match any article at all.