Create Event Trend

Aggregate semantic event matches into a compact, dense time series on the server.

POST/api/event-trends

Authorizations

Bearer

Authorizationstringheader

Required Bearer API key for programmatic World access.

Example: Bearer nos_sk_...

Body

application/json

querystringrequiredbody

Semantic topic definition.

Example: openai lawsuits

fromdaterequiredbody

Inclusive UTC start date.

Example: 2026-06-01

todaterequiredbody

Exclusive UTC end date.

Example: 2026-09-01

intervalenumbody

day, week, month, or quarter.

Example: month

min_similaritynumberbody

Inclusive exact-cosine threshold; defaults to 0.35.

Example: 0.35

filtersobjectbody

World Search filter DSL.

Example: {}

group_byenumbody

Optional single categorical split such as sentiment or country.

Example: sentiment

How to use this endpoint

guidance

Use Event Trend for a semantic signal over time without downloading the matching events. Buckets are stable under wider date ranges because retrieval uses fixed calendar-quarter partitions. Treat truncated buckets as lower bounds.

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.

idstring

Short-lived handle for bucket drill-down.

Example: tr_4a45c76c941f482e

approximateboolean

Always true because semantic candidate retrieval is bounded.

Example: true

bucketsobject[]

Dense chronological time-series buckets.

Example: [{ start, event_count, coverage_sum, similarity_sum, truncated, groups }]

buckets[].startdate

Inclusive bucket start date.

Example: 2026-06-01

buckets[].event_countinteger

Retained semantic matches in the bucket.

Example: 184

buckets[].coverage_suminteger

Sum of distinct-source coverage across retained events.

Example: 612

buckets[].similarity_sumnumber

Sum of exact semantic similarities across retained events.

Example: 123.84

buckets[].truncatedboolean

True when the quarter candidate budget filled and more matches may exist.

Example: false

buckets[].groupsobject

Optional group-value metrics.

Example: { "negative": { "event_count": 91, "coverage_sum": 318, "similarity_sum": 62.17 } }

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.

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 — A body field has the wrong type or form, such as a limit sent as a string; the message names it.

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.