Similar events

Find the events closest in meaning to one event, most similar first, to discover historical analogues and recurring story patterns around it.

Explanation

Finds the events across the NOSIBLE World V2.0 archive that are closest in meaning to one event, most similar first. Use it to discover historical analogues and recurring story patterns around an event, such as earlier supply shocks that resemble today's.

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

Request

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
viewenumquery

The record each event is returned as: lite (the default), the event without its evidence, or full, the complete record. Any other value is a 422 validation_error. About records on Event details lists both.

Example: lite

include_vectorbooleanquery

true adds each event's embedding, oai_vector (3,072 values, comma-separated), to either view. Defaults to false.

Example: false

datedaterequiredpath

Archive date in YYYY-MM-DD format.

Example: 2026-07-20

event_idstringrequiredpath

Canonical event identifier.

Example: 2026-07-20_en_JP_v1_NQA5mXKS5x7MUUbwQAAAABDCQAAAInpsKAEpoAAAAAA_ehrkVV2W

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 (none are stored in the current archive).

Example: true

Response

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.

viewstring

The view the events are returned in: lite (the default) or full. See About records on Event details.

include_vectorboolean

true when the request asked for the embedding with include_vector=true; absent otherwise.

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, each a record in the requested view (lite unless view=full) with its similarity and retrieval.

neighbors[].event_idstring

Stable event identifier.

neighbors[].versionstring

Event record version: "2.0-preview".

neighbors[].eventobject

The event in its original language: date, language, title, description and points.

neighbors[].event.datedate

World archive date of the event.

neighbors[].event.languagestring

ISO 639-1 code of the event's original language.

neighbors[].event.titlestring

Headline, in the original language.

neighbors[].event.descriptionstring

Short narrative, in the original language.

neighbors[].event.pointsstring[]

Key facts of the event, one sentence each.

neighbors[].englishobject

The event in English: title, description and points, translated when the original language is not English.

neighbors[].coverageobject

total_coverage, total_netlocs, coverage_concentration_index, first_seen, last_seen and most_seen, as in Event details.

neighbors[].locationsobject[]

Places of the event, its own place first, then places named in it, as in Event details.

neighbors[].signalsobject

Sentiment, materiality, time horizon and forward-looking signals with their class probabilities, as in Event details.

neighbors[].tickersobject[]

Listed companies the event concerns, in the Event details format without why. Empty when has_tickers is false.

neighbors[].has_tickersboolean

Whether tickers is non-empty.

neighbors[].entitiesobject

Named entities by NER type, {TYPE: [{name, mention_count, confidence}]}, as in Event details.

neighbors[].sentimentsobject

Entity-level sentiment grouped by entity type. Each item has name, sentiment_label (positive, neutral or negative), and sentiment_score, the final Percentage Margin Z-score.

neighbors[].ontologiesobject[]

Classifications of the event, most probable first, as in Event details.

neighbors[].oai_vectorstring

Only with include_vector=true: the event's 3,072-dimension embedding (text-embedding-3-large), comma-separated.

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, records like neighbors. Always empty in V2.0: 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 body is shown in the response example.
400invalid_json — The request body is not JSON. Every error body, 401 included, is {error, message, status}.
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.
422validation_error — The request is well formed but the API cannot decode or validate it: an unknown body field or query parameter, a missing required parameter, a value of the wrong type, an empty and, or or not, a date that is not a calendar date (in the path, the query or the body), an unknown enum value or a reversed range. The message names the parameter and what is wrong.
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.
503api_key_metering_unavailable — API key usage metering is temporarily unavailable, so the request was not served; wait for the Retry-After header (30 seconds) and retry.
502backend_error — The World backend could not be reached or did not return a valid response; retry shortly.
504backend_timeout — The World backend did not answer within 300 seconds; narrow the request (for example with a date window) or retry.