For all time

Search the dated event archive with metadata, lexical, semantic, or hybrid retrieval.

POST/api/v2.0/search

Authorizations

Bearer

Authorizationstringheader

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_...

Body

application/json

viewenumbody

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_vectorbooleanbody

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

Example: false

search_typeenumbody

metadata, lexical, semantic, or hybrid. Omitted, it is hybrid with q, semantic with vector and metadata otherwise. lexical needs q, and semantic and hybrid need q or vector: sent without them, the request is a 422 validation_error.

Example: hybrid

qstringbody

Text query. Used for lexical, semantic, and hybrid retrieval.

Example: oil supply disruption

dateobjectbody

Optional inclusive window {from, to, include_live}, each date written YYYY-MM-DD; include_live opts into the newest slices. Set from and to explicitly for reproducible queries.

Example: {"from":"2026-07-01","to":"2026-07-20","include_live":true}

filtersobjectbody

Keeps only the events that match it, in the results, in total and in facets. A JSON object of field conditions, combined with and, or and not, with bbox and geo_radius for places: {"sentiment": "negative", "total_coverage": {"gte": 50}}. Filter syntax below lists every operator; Search Schema lists the fields.

Example: {"gics_sector":"Energy"}

limitintegerbody

Number of events to return: 50 unless sent, at most 10,000 (a larger value is capped at 10,000). Page further with offset.

Example: 20

offsetintegerbody

Number of matching events to skip before returning the page.

Example: 0

vectornumber[]body

Caller-supplied embedding for semantic retrieval. Its length must match the configured HNSW dimension.

Example: [0.012, -0.004, ...]

query_vectornumber[]body

Alias for vector.

Example: [0.012, -0.004, ...]

sortobject[]body

Sort rules such as [{ by: 'total_coverage', desc: true }].

Example: [{"by":"total_coverage","desc":true}]

facetsstring[]body

Field names (or their aliases) to count over the events the search returns: the same events as total, live days included. Counts answer under each field's canonical name.

Example: ["country","sentiment"]

embedding_modelenumbody

Embedding model for semantic or hybrid retrieval. The supported value is openai.

Example: openai

semantic_filter_modeenumbody

Semantic filter strategy: auto, usearch, or exact.

Example: auto

max_datesintegerbody

Maximum archive dates the planner may visit.

Example: 30

explainbooleanbody

Include retrieval planning details where supported.

Example: false

querystringbody

Alias for q. Use one name consistently in a client; q is the canonical short form.

Example: oil supply disruption

includestring[]body

["explain"] adds retrieval planning details, as explain=true does.

Example: ["explain"]

exact_vector_max_candidatesintegerbody

Maximum metadata-qualified candidates to score exactly when semantic_filter_mode is exact.

Example: 100000

semantic_candidatesintegerbody

Candidate budget of semantic and hybrid search when the window and filters admit more than 500,000 archive events (and on each live day's own index with include_live): the nearest events retrieved before the exact rerank; total counts those at or above the 0.20 similarity floor that pass the filters and window. When they admit at most 500,000, every one is scored exactly and the budget does not apply. Defaults to 5,000, at most 50,000. It never changes with limit or offset.

Example: 5000

How to use this endpoint

guidance

Use global World Search when the question spans dates and you need metadata, lexical, semantic, or hybrid retrieval over event records. Keep the date window explicit in production so results are reproducible.

Filter syntax

filters

filters keeps only the events that match it: the search, its total and its facets all count those events and no others. It is a JSON object, and an event must satisfy every key of it. A key is a field name, one of and, or and not, or one of the geographic shapes bbox and geo_radius. Search Schema (GET /api/v2.0/search/schema) lists every field with its type (string, number, boolean, date or string_set), its aliases (countries for country, orgs for entity_org, tickers for ticker) and the operators each type takes; fetch it rather than copying a list from here.

A field's condition takes one of three forms. A bare value is equality: {"sentiment": "negative"}. An array means any of its values: {"sentiment": ["positive", "neutral"]}. An object applies operators, and every operator in it must hold: {"total_coverage": {"gte": 50, "lt": 500}}. A condition is never null (to find events without a value, send {"missing": true}), and an operator object is never empty.

Strings are compared exactly on a string field, so write a value as the event carries it: {"gics_sector": "Energy"} matches and "energy" does not (the Ontology directory and a search's facets list the values). contains and prefix ignore case. A string_set field (entity_gpe, entity_loc, entity_org, entity_person, entity_product, ticker, isin, figi, lei, wiki_qid and the *_top3 classification fields) holds several values per event, and every operator on it ignores case and extra spaces. entity_any, also entities, is every entity_* field at once. V1.2's city, required_ontology_below_floor, entity_event, entity_fac, entity_language, entity_law, entity_norp and entity_work_of_art are not fields of V2.0: filtering on one is a 422.

A date is a string in YYYY-MM-DD form, such as "2026-09-30": in a condition on the date field (the event's archive date) and in the request's own date window ({"from", "to", "include_live"}). The window chooses which archive days are searched; filters then apply to those days, so a request can carry both. A timestamp, a date without its leading zeros ("2026-9-1") and any other form is a 422 validation_error.

World Search and date-grouped search answer a filter they cannot read with a 422 validation_error whose message names the path of the problem: an unknown field (with the closest known name), an operator the field's type does not take, a value of the wrong type, a null, an empty and, or or not, a between or bbox written backwards. Event Trend reads and checks the same syntax.

A complete filter

and, or, not and a range togetherobject

Negative events of the United States or the United Kingdom, without a listed company, reported by at least 50 documents. Keys beside each other are an and, and and, or and not nest to any depth.

Example: {"and": [{"sentiment": "negative"}, {"or": [{"country_iso": "US"}, {"country_iso": "GB"}]}, {"not": {"has_tickers": true}}, {"total_coverage": {"gte": 50}}]}

Operators

eqall types

Equal to the value. On a string_set field, the event has the value.

Example: {"country_iso": {"eq": "US"}}

neqstring, number, boolean, date

Not equal to the value. Events with no value match.

Example: {"gics_sector": {"neq": "Energy"}}

inall types

Equal to any of the values. On a string_set field, the event has at least one of them.

Example: {"language": {"in": ["en", "fr"]}}

not_inall types

Equal to none of the values. Events with no value match.

Example: {"entity_org": {"not_in": ["nvidia"]}}

allstring_set

The event has every one of the values.

Example: {"entity_org": {"all": ["nvidia", "openai"]}}

existsstring, number, boolean

true: the event has a value. false: it has none.

Example: {"gics_sector": {"exists": true}}

missingstring, number, boolean

true: the event has no value. false: it has one.

Example: {"gics_sector": {"missing": true}}

gt, gte, lt, ltenumber, date

Greater than, at least, less than, at most. The value is a number, or a date for a date field.

Example: {"total_coverage": {"gte": 50}}

betweennumber, date

[low, high], both ends included. The low end may not be above the high end.

Example: {"date": {"between": ["2026-09-01", "2026-09-30"]}}

containsstring, string_set

A value contains the text, ignoring case. The argument is a string or an array of strings, any of which may match. The entity fields hold millions of distinct names, and a field with more than 1,000,000 of them (entity_org, entity_person and others) refuses contains and prefix: use eq or in with a name that Find entities returns.

Example: {"title": {"contains": "oil"}}

prefixstring, string_set

A value starts with the text, ignoring case. Refused on the same entity fields as contains.

Example: {"title": {"prefix": "oil"}}

Combining conditions

andfilter[]

An array of filter objects, all of which must match.

Example: {"and": [{"sentiment": "negative"}, {"has_tickers": true}]}

orfilter[]

An array of filter objects, at least one of which must match.

Example: {"or": [{"country_iso": "US"}, {"country_iso": "GB"}]}

notfilter

One filter object, which must not match. Events that lack the field match too.

Example: {"not": {"has_tickers": true}}

Geography

bboxnumber[4]

[west_lng, south_lat, east_lng, north_lat]: events whose own place (the lat and lng fields) is inside the box, its edges included. Longitudes run from -180 to 180 and latitudes from -90 to 90; west may not be east of east, or south above north, so a box across the 180th meridian is two boxes joined with or. Events with no place never match a bbox, so not {bbox} includes them. geo_bbox is accepted as the same key.

Example: {"bbox": [-10, 35, 30, 60]}

geo_radiusobject

{lat, lng, km}: events whose own place is within km kilometres of the point, measured along the earth's surface. lat is from -90 to 90, lng from -180 to 180 and km above 0. radius is accepted as the same key and lon as lng. Events with no place never match.

Example: {"geo_radius": {"lat": 51.5, "lng": -0.1, "km": 50}}

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.

totalinteger

Events in the result set, the same on every page (limit and offset only choose the slice). Metadata and lexical search: every matching event. Semantic and hybrid search: every event that passes the filters and window and has a cosine similarity of at least 0.20 to the query, in every semantic_filter_mode, when the window and filters admit at most 500,000 archive events; above that, those among the semantic_candidates nearest to the query (5,000 unless sent).

total_exactboolean

true when total counts every match: every event the window and filters admit was scored. false when the window and filters admit more than 500,000 archive events and the vector index returned its whole candidate budget, so more events above the similarity floor may exist beyond it: narrow the window or filters to count them all, or send a larger semantic_candidates to count further.

total_capped_atinteger

Only when total_exact is false: the candidate budget that capped total.

countinteger

Events in this page.

limitinteger

Page size applied.

offsetinteger

Events skipped.

eventsobject[]

The events, as lite records unless view=full (About records on Event details lists both). A full record adds provenance, availability, triples, each ticker's why and v2_preview_success.

events[].event_idstring

Stable event identifier.

events[].versionstring

Event record version: "2.0-preview".

events[].eventobject

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

events[].event.datedate

World archive date of the event.

events[].event.languagestring

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

events[].event.titlestring

Headline, in the original language.

events[].event.descriptionstring

Short narrative, in the original language.

events[].event.pointsstring[]

Key facts of the event, one sentence each.

events[].englishobject

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

events[].coverageobject

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

events[].locationsobject[]

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

events[].signalsobject

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

events[].tickersobject[]

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

events[].has_tickersboolean

Whether tickers is non-empty.

events[].entitiesobject

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

events[].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.

events[].ontologiesobject[]

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

events[].oai_vectorstring

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

events[]._scorenumber

Overall retrieval score.

events[]._lexical_scorenumber

Lexical component of the score (lexical and hybrid search).

events[]._semantic_scorenumber

Cosine similarity to the query (semantic and hybrid search); at least 0.20.

events[]._retrievalstring

Retrieval path that found the event.

events[]._search_datedate

Archive date the record was read from.

facetsobject

Counts for the fields requested in facets, over the events total counts; empty when none were requested.

query_took_msinteger

Total time in milliseconds.

embedding_msinteger

Time spent embedding the query.

search_msinteger

Time spent searching.

date_windowobject

from, to, include_live and archive_cutoff of the search.

missing_datesdate[]

Days of the window with no data, in date order, as Event Trends lists them; empty when the window has every day. The search covers the days the archive has.

search_typestring

Retrieval mode used.

errorsobject[]

Non-fatal stage errors; empty when none.

Responses and errors

HTTP

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

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.