Similar events

Find semantically similar events to a canonical event.

GET/api/v2.0-preview/events/{date}/{event_id}/similar

Authorizations

Bearer

Authorizationstringrequiredheader

Required Bearer API key. Programmatic access to the World API needs a key; browsing nosible.world in a browser does not.

Example: Bearer nos_sk_...

Parameters

query & path

datedaterequiredpath

Archive date in YYYY-MM-DD format.

Example: 2026-07-20

event_idstringrequiredpath

Canonical event identifier.

Example: 2026-07-20_en_US_v1_...

limitintegerquery

Maximum neighbors to return.

Example: 10

include_livebooleanquery

Also search the live days after the archive cutoff. Defaults to false.

Example: false

include_threadbooleanquery

Include stored story-thread predecessors.

Example: true

How to use this endpoint

guidance

Use Similar Events to discover historical analogues and story threads. Similarity is a ranking signal, not a claim that two events are causally related. neighbors are computed against the archive-wide HNSW index; thread is the persisted backwards story chain.

Response body

application/json

These are the fields you can build against. Nested names use dot notation; optional sections are called out in their descriptions.

schemastring

Response schema name.

event_idstring

The event the neighbours are similar to.

datedate

Its date.

limitinteger

Neighbour cap applied.

floordate

Earliest date a neighbour may have: the start of the archive your key can read.

min_similaritynumber

Similarity floor applied.

neighborsobject[]

The most similar events across the archive, most similar first.

neighbors[].event_idstring

Neighbour's event identifier.

neighbors[].datedate

Neighbour's date.

neighbors[].titlestring

Neighbour's headline, in its original language.

neighbors[].countrystring | null

Country of the neighbour's own place (its first location); null when it has none.

neighbors[].similaritynumber

Cosine similarity of the two events' embeddings.

neighbors[].retrievalstring

Where the neighbour was found, such as archive_hnsw (the archive's vector index).

threadobject[]

Stored story-chain predecessors. Always empty in V2.0-preview: its events carry no stored story chain, so use neighbors.

errorsobject[]

Non-fatal retrieval errors; empty when none.

took_msinteger

Server time in milliseconds.

Responses and errors

HTTP

200Request succeeded. The response body is shown in the panel on the right.

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

401api_key_required — No API key was sent. Send it as Authorization: Bearer <key> or the api-key header.

401invalid_api_key — The API key is invalid or has been revoked.

403access_denied — The requested archive date is outside the caller's World tier.

404not_found — The requested date, entity, ticker, or event does not exist in the accessible index.

410cursor_expired — The cursor was minted against a replaced index build. Restart pagination from the first page.

429rate_limited — The request exceeded the endpoint or account rate limit. Respect Retry-After when supplied.

501backend_not_configured — The World backend is not configured for this deployment.

503api_key_auth_unavailable — API key authentication is temporarily unavailable; retry shortly.

502backend_error — The BFF could not obtain a valid response from the World backend.

504backend_timeout — The World backend or an upstream data source timed out.