By entity

Retrieve cursor-paged events that mention one canonical entity across any date window.

GET/api/entities/events

Authorizations

Bearer

Authorizationstringheader

Optional Bearer API key. Public requests use the rolling window; enterprise keys unlock the full archive.

Example: Bearer nos_sk_...

Parameters

query & path

typestringrequiredquery

NER type, or ANY to merge all indexed entity types.

Example: ORG

namestringrequiredquery

Canonical display name returned by /resolve.

Example: Nvidia

limitintegerquery

Page size. Defaults to 50, maximum 500.

Example: 50

cursorstringquery

Opaque cursor returned by the previous response.

Example: eyJ2Ijox...

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

orderenumquery

Event ordering, newest or oldest first.

Example: desc

includeenumquery

Projection selector: event_lite or event_full. This is a single query value, not an array.

Example: event_lite

include_vectorbooleanquery

Include the event embedding when the caller's tier and the selected projection allow it.

Example: false

include_livebooleanquery

Include the newest live slices when enabled for the deployment.

Example: true

How to use this endpoint

guidance

Use this route to build a company or person timeline. Resolve the canonical name first, then page with the opaque cursor; do not infer a cursor from dates or offsets. Store the as_of markers with research results.

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

Stable entity timeline contract identifier.

Example: nosible_world_entity_events_v1

entityobject

Canonical entity type, display name, and normalized lookup form.

Example: { "type": "ORG", "name": "Nvidia", "normalized": "nvidia" }

totalinteger

Total number of matching events before the current page is sliced.

Example: 1842

countinteger

Number of events returned in this page.

Example: 100

eventsobject[]

Event records for the route. The projection varies by endpoint: dated list/search routes return lite records, while global search and full-detail routes can include richer fields.

Example: [{ event_id, event, signals, ontology, coverage }]

next_cursorstring | null

Opaque cursor for the next page. Send it back unchanged; null means the result set is exhausted.

Example: eyJ2Ijox...

orderstring

Applied event order, newest or oldest first.

Example: desc

date_windowobject

Effective date window, indexed last date, archive cutoff, and live-overlay decision.

Example: { "from": "2026-01-01", "to": "2026-07-20", "index_last_date": "2026-07-20", "archive_cutoff": "2026-07-20", "include_live": false }

live_eventsobject[]

Ephemeral live-overlay events when include_live is enabled; they are not included in total or cursor pagination.

Example: []

hydration_missesinteger

Number of events that could not be hydrated into the requested projection.

Example: 0

as_ofobject

Index build and archive freshness markers for reproducible downstream analysis.

Example: { "index_build": "world-v1.2", "archive_cutoff": "2026-07-01" }

took_msnumber

Timeline query duration in milliseconds.

Example: 59

Responses and errors

HTTP

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

400invalid_request — The date, filter, cursor, identifier, or request combination is invalid.

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

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.

404unknown_entity — The requested entity is not present in the index.