GET /similar/{id}
Articles similar to a given one.
More-Like-This over the semantic index, deduplicated across outlets and excluding the seed. Equivalent to the `find_related` MCP tool. Credits: 2, for the vector search behind it. Pass estimate=true to get the exact range without running the call, or max_credits to refuse anything costlier.
-
id— The seed article id.
More-Like-This: the seed article's own embedding is the query, so this finds coverage that is about the same thing without anyone having to write a query that describes it. Results are deduplicated across outlets and exclude the seed.
Parameters
| Name | Type | Description |
|---|---|---|
| limit | integer | Results per page, 1-100 (default 10). |
| view | `full` · `compact` | How much of each hit to return. `full` (default) is the whole Article; `compact` keeps id, title, url, source, published_at, language, story_id and score. Use compact when results feed a model. |
| estimate | boolean | Return this call's price instead of running it: the credit range, a breakdown, your remaining credits and whether the call would run. A preview costs 0 credits. |
| max_credits | integer | Refuse the call, at no cost, when its worst case would cost more than this many credits. The refusal carries the estimate. |
Response
The same shape as /search, with mode reported as
similar and total_relation as approximate — nearest-neighbour retrieval ranks
a bounded candidate set rather than scoring the whole corpus, so the total is a count of what was considered.
view=compact applies here too, and so do partial and coverage: a seed
whose partition could not be read is a 503, not an empty list.
When to use this instead of a new search
When an agent has a result in hand and wants "what else covered this". Writing a fresh query from an article's title is the obvious alternative and it is worse: the title is one framing of the story, so a query built from it inherits that framing and drifts. The embedding does not.
It also differs from clustering, which is the other way to get "related":
| You want | Use |
|---|---|
| This exact event, as one object | /stories/{id} with the seed's story_id — counts, outlets, when, what it is about, its newest articles |
| Every article about this exact event | /search?story_id=… — the cluster is exact and precomputed |
| Articles about related events | This endpoint — similarity is a gradient, so it crosses story boundaries |
Example
curl -s "https://api.unzoi.com/similar/20260826073000-a1b2c3?limit=10" \
-H "x-api-key: $UNZOI_KEY"