World API/EVENT SEARCH

For a date range

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

POST/api/v2.0-preview/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
group_byenumrequiredbody

Grouping dimension; currently date.

Example: date

vectorsnumber[][]requiredbody

One or more anchor embeddings. Each production vector must contain exactly 3,072 floating-point values.

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

dateobjectrequiredbody

Inclusive date window. Set include_live=true to include newest active slices.

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

filtersobjectbody

The World Search filter DSL.

Example: {"language":"en"}

includestring[]requiredbody

Projection selector; include factor for the grouped factor response.

Example: ["factor"]

per_date_limitintegerbody

Candidate retrieval budget for each date; defaults to 1000.

Example: 1000

min_scorenumberbody

Inclusive semantic score floor; defaults to 0.2.

Example: 0.35

Related in NOSIBLE World

World · Map ↗Open this result set on the event map, filtered to the same windowWorld · Trend ↗Plot the same query as a historical event signalWorld · Chaos ↗Watch the unfiltered crawl the ontology is built from

How to use this endpoint

guidance

Use this endpoint when a semantic definition must be evaluated independently across dates. Request the factor projection and set date.include_live=true when the newest active slices should be included.

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.

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; shorten the window or raise min_score when total nears it.

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; join them to groups by date.

events[].datedate

Archive date of the event.

events[].event_idstring

Event identifier.

events[].titlestring

Headline, in the original language.

events[].countrystring

Country of the event's own place (its first location; see Event details). Empty when the event has no place.

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.

events[].total_coverageinteger

Source documents in the event.

events[].total_netlocsinteger

Distinct source sites in the event.

events[].coverage_concentration_indexnumber

Concentration of the coverage across sites, from 0 to 1.

events[].materiality_scorenumber

Continuous materiality from 0 to 1.

events[].sentimentstring

positive, neutral or negative.

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

Whether the date's candidate budget filled, so more matches may exist.

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.

statsobject

Totals over the dates: dates requested and scanned, eligible, candidate and matched events, and truncation.

timing_msobject

Server time in milliseconds.

Responses and errors

HTTP
200Request succeeded. The response body is shown in the panel on the right.
400invalid_request — The grouped request is invalid or omits required date, vector, or projection fields.
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.
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.