Time and point in time

Every answer states its own time: the value's own timestamp, when it was last stored or confirmed, and, where a route supports it, what was known at an earlier instant.

Time conventions

kind of time	how it is written
a date	YYYY-MM-DD, for every daily-or-coarser fact: a bar's session date, a period's start and end, a close's session_date
an instant	UTC with microseconds: YYYY-MM-DDTHH:MM:SS.ffffffZ, for example 2026-09-25T20:00:02.000000Z. It sorts as a string and can be passed back as known_at. An intraday bar carries its opening instant as start

The OpenAI-compatible AI routes keep OpenAI's integer Unix timestamps (created, created_at).

Periods

A value series states its period kind in period_kind: calendar_day, week, month, quarter, calendar_year or marketing_year. Each value carries its period's label, start, and end. Daily market facts are dated by their session (session calendars).

source_time and refreshed_at

field	answers
source_time	"How old is this value?": the value's own timestamp (a quote's trade time, an exchange tick)
refreshed_at	"Is the stored copy current?": when the served fact was last stored or confirmed

A timestamp that is not given is null, or the field is not served where no value of that kind carries one (series observations, positioning reports).

known_at

known_at must be an instant with a timezone (2026-09-20T12:00:00Z). A date alone, or an instant without an offset, is 422 invalid_request. The routes that take it are listed under point in time.

Freshness

Besides source_time and refreshed_at, answers state how current they are with these fields:

field	meaning
source_lag_seconds (quotes)	how old the price already was when it was recorded
observed_through (value series)	the end of the newest period with a value published when refreshed_at last confirmed the series
source_lag_days (value series)	calendar days from observed_through to refreshed_at: the publication delay
freshness.stale	true when the stored copy is behind its source

stale is never about publication frequency: a monthly series whose newest month is old by design is not stale, and source_lag_days carries that delay. When stale cannot be judged, it is null and freshness.field_states.stale says why (for example not_assessed). How each bar family is judged is on price history.

A whole answer whose stored data is too old to serve is refused 503 temporarily_unavailable instead (error codes).

Point in time

A point-in-time answer gives the data as it was knowable at the instant you pass as known_at, on a route that declares it:

route	as-of meaning
/v1/series/{key}/observations, /v1/series/{key}/projections	each period's value as known at the instant (series values)
/v1/securities/{symbol}/financials, /filings, /insider-transactions	what the filings accepted at or before the instant asserted (filings and financials)
/v1/futures/{root}/positioning	the reports as they were held at the instant (positioning)
/v1/securities/{symbol}/thesis, /v1/themes	the thesis written latest at or before the instant, and the themes snapshot of then (digests, theses, and themes)

On any other route known_at is refused 422 invalid_request, and the message names the routes that honor it. A dataset's point_in_time in GET /v1/datasets says the same machine-readably (the dataset catalog).

curl "https://api.tauric.ai/v1/series/us.cpi.all_items.sa/observations?known_at=2026-09-20T12:00:00Z" \
  -H "Authorization: Bearer $TAURIC_API_KEY"

What a point-in-time answer states

A series answer (observations, projections, the latest value), a supply-and-demand member, and a positioning answer carry a point_in_time block; the other routes that take known_at state the instant they answer as known_at:

field	meaning
known_at	the instant asked; null on a current read
supported	true: the route answers known_at
since	the earliest instant the route can answer for this data
complete	under known_at: true when the instant is at or after since. Null on a current read

An instant before since is answered with complete false and no values before since, with the reason before_point_in_time_history; that does not mean no data existed then.