By ontology

Retrieve events classified into one ontology field and value, including ranked top-three matches.

GET/api/v2.0/ontology/events

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

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

fieldstringquery

Indexed ontology field, such as gics_sector. Supply field, or supply both ontology and level instead.

Example: gics_sector

valuestringrequiredquery

Ontology class to retrieve.

Example: Energy

matchstringquery

top1 precision match or top3 recall match.

Example: top3

fromdatequery

Inclusive lower date bound in YYYY-MM-DD format.

Example: 2026-01-01

todatequery

Inclusive upper date bound in YYYY-MM-DD format.

Example: 2026-07-20

limitintegerquery

Page size.

Example: 100

cursorstringquery

Opaque cursor returned by the previous page.

Example: eyJ2Ijox...

orderenumquery

Event ordering, newest or oldest first.

Example: desc

ontologystringquery

Ontology id or slug from the directory, such as gics. Required with level when field is omitted.

Example: gics

levelstringquery

Local level name returned by the directory, such as sector for GICS or tier_1 for IAB. Required with ontology when field is omitted.

Example: sector

include_livebooleanquery

Defaults to true. Include published slices after the archive index, including today and yesterday (UTC). Set false for archive-only retrieval. GET uses the query string; POST uses a JSON boolean.

Example: true

How to use this endpoint

guidance

Use ontology retrieval to turn a taxonomy class into a clean event universe. Select the class with either field=gics_sector&value=Energy or ontology=gics&level=sector&value=Energy. Directory levels are local names such as sector or tier_1, and are not necessarily the indexed filter field names; copy a hierarchy node's events_url to use the correct pair. Choose top1 for precision; choose top3 when recall matters and you are comfortable with parent/child class overlap. include_live defaults to true, as on the entity, ticker and polygon timelines. Both top1 and top3 include today and yesterday within the requested UTC dates; set include_live=false for archive-only retrieval.

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.

classificationobject

The class requested: field, value and match (top1 or top3), and ontology and level when the request names them instead of field.

classification.fieldstring

Taxonomy field, such as gics_sector.

classification.valuestring

Class value.

classification.matchstring

top1 (the event's most probable class) or top3 (any of its three most probable).

totalinteger

Events matching the request before paging.

countinteger

Events in this page.

orderstring

Event order: desc (newest first, the default) or asc.

date_windowobject

The effective inclusive window searched: from, to, index_last_date (the last date with indexed events), archive_cutoff (the last archive date) and include_live. Entity and ticker timelines with include_live=true default to today (UTC) and accept a window wholly after the archive boundary, such as today alone. Their live_events are records in the same format, constrained by both bounds, marked ephemeral and returned on the first page only, outside archive total and cursor paging. Without include_live the default upper bound is the archived index.

date_window.fromdate

First date searched.

date_window.todate

Last date searched.

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.

next_cursorstring | null

Opaque cursor for the next page; send it back unchanged. null when there are no more events.

hydration_missesinteger

Events that matched but could not be read; normally 0.

as_ofobject

index_build and archive_cutoff: the index that answered. Store them with results to reproduce them.

took_msinteger

Server time in milliseconds.

languagestring[]

Languages the events were filtered to with the language parameter; empty when not filtered.

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 belongs to a replaced index build; restart 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.

404unknown_ontology_value — The field/value combination is valid but the requested class has no indexed match; check the schema or resolve the class again.

422cursor_filter_mismatch — The cursor was created for a different ontology field, value, or match mode.