For a date range

Retrieve bounded semantic results grouped by date, with an optional live overlay for the newest slices.

POST/api/v2.0/search

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

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

group_byenumrequiredbody

Grouping dimension; currently date.

Example: date

vectorsnumber[][]body

Anchor embeddings: 1 to 64 vectors, each exactly 3,072 numbers (text-embedding-3-large, the embedding oai_vector returns). Send vectors or vector_texts, not both; one of them is required.

Example: [[0.0, 0.0, ...]] (3,072 values)

vector_textsstring[]body

Plain-language anchors the server embeds in place of vectors (text-embedding-3-large): 1 to 64 texts, each 1 to 8,192 bytes of UTF-8 once trimmed; a blank or longer text is rejected. The embeddings come back in resolved_vectors, to send as vectors later without embedding again. Send vector_texts or vectors, not both; one of them is required.

Example: ["AI chip supply constraints"]

vector_aggregateenumbody

How an event's similarities to several anchors combine into its score: max (the default: its best match), mean (the average) or softmax (an average weighted towards the best matches, between mean and max). With one anchor all three give the same score.

Example: max

score_vectorsnumber[][]body

Vectors to measure, not search with: up to 64, each 3,072 numbers. They widen nothing and change neither score nor which events match; each event's score_vector_scores lists its cosine similarity to each one, in request order. Send score_vectors or score_vector_texts, not both.

Example: [[0.0, 0.0, ...]] (3,072 values)

score_vector_textsstring[]body

Plain-language statements the server embeds in place of score_vectors, under the same limits as vector_texts (up to 64 texts of 8,192 bytes). The embeddings come back in resolved_score_vectors.

Example: ["chip shortages are easing", "chip shortages are worsening"]

dateobjectrequiredbody

Inclusive date window of up to 120 days with data; from and to are both required, written YYYY-MM-DD. Days with no data are listed in missing_dates. Set include_live=true to include the newest live days.

Example: {"from":"2026-09-15","to":"2026-09-17","include_live":true}

filtersobjectbody

Only events that match it are searched, matched and counted in each group's eligible totals. The World Search filter syntax: field conditions combined with and, or and not, with bbox and geo_radius for places. Filter syntax on For all time lists every operator; Search Schema lists the fields.

Example: {"language":"en"}

includestring[]body

Optional. ["factor_columns_v1"] returns the events as columns of values instead of records; view does not apply to it. No other value is needed.

Example: ["factor_columns_v1"]

per_date_limitintegerbody

Candidates retrieved for each anchor and date: from 1 to 10,000, defaulting to 1,000. Dates × anchors × per_date_limit may not exceed 2,000,000 retrievals, and that product × (anchors + score vectors) may not exceed 50,000,000 exact scores: narrow the window, the anchors, the score vectors or per_date_limit.

Example: 1000

min_scorenumberbody

Inclusive floor on an event's score, from -1 to 1; defaults to 0.2.

Example: 0.35

How to use this endpoint

guidance

Use date-grouped search to build a daily time series from one or more anchors over a window of up to 120 days. An anchor is a vector you send (vectors) or a plain-language text the server embeds for you (vector_texts): send up to 64 of either, and vector_aggregate sets how an event's similarities to several of them combine into its score. score_vectors and score_vector_texts add vectors that are only measured, never searched with: each matched event reports its similarity to each of them, so one request can score the same events for a topic and for a direction within it, such as "shortages are easing" and "shortages are worsening". Each event is a record in the requested view (lite unless view=full) with its group date and scores; groups summarise each day with denominators. include=["factor_columns_v1"] returns the events as columns instead of records. A window that includes days with no data is answered for the days it has, with the others in missing_dates. limit, offset, sort and facets do not apply to a grouped search: per_date_limit is its retrieval budget. The filters are the World Search filter syntax, set out on For all time.

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.

revisioninteger

Revision of the response format.

search_typestring

semantic.

group_bystring

Grouping dimension: date.

vector_aggregatestring

How an event's similarities to several anchor vectors combine into its score: max, mean or softmax.

per_date_limitinteger

Candidates retrieved per anchor vector and date.

min_scorenumber

Score floor applied.

totalinteger

Matched events across all dates.

candidate_eventsinteger

Candidates scored across all dates.

response_event_limitinteger

Most events one response may carry: 5,000 lite records or 1,000 full ones (fewer with many anchor vectors). Above it the request is a 422 grouped_response_too_large; shorten the window or raise min_score.

resolved_vectorsnumber[][] | null

The anchor vectors embedded from vector_texts, to send as vectors in later requests; null when vectors were sent.

resolved_score_vectorsnumber[][] | null

The same for score_vector_texts; null when none were sent.

eventsobject[]

Matched events, flat, as records in the requested view with their per-result fields; join them to groups by date.

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

The group (archive date) of the event.

events[].scorenumber

Aggregate score over the anchor vectors.

events[].vector_scoresnumber[]

Cosine similarity to each anchor vector.

events[].score_vector_scoresnumber[]

Cosine similarity to each score vector; empty without score vectors.

groupsobject[]

One summary per date scanned.

groups[].datedate

The date.

groups[].matched_countinteger

Matched events on the date.

groups[].candidate_countinteger

Candidates scored on the date.

groups[].candidate_retrieval_hitsinteger

Candidates the vector index returned for the date, before deduplication across anchor vectors.

groups[].truncatedboolean

true when an anchor's candidate budget (per_date_limit) filled with its farthest candidate still at or above min_score, so events above min_score may have been left out: raise per_date_limit. false means no event of the date above min_score was left out (by the index's ranking).

groups[].eligibleobject

All events on the date that pass the filters, matched or not: count, total_coverage, total_netlocs, total_materiality and total_sentiment_weight. Use them as denominators.

date_windowobject

from, to, include_live and archive_cutoff.

missing_datesdate[]

Days of the window with no data, in date order, as Event Trends lists them; empty when the window has every day. They have no groups: they are not zero activity.

statsobject

Totals over the dates: dates requested and scanned, eligible, candidate and matched events, and truncated_dates and truncated, which count the dates where groups[].truncated is true.

timing_msobject

Server time in milliseconds.

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.

422grouped_response_too_large — The request exceeds the bounded grouped response budget; shorten the window or raise the score floor.

503grouped_search_busy — The grouped-search worker pool is full; retry after backoff.