Developer documentation API v1

Temporal evidence and provenance

Bitemporal reasoning, revision-aware retrieval and lineage from observation to decision.

A revision cannot travel backward in time

Initial data arrives before a decision cutoff; a later correction arrives after the cutoff and is excluded from that decision’s replay. — Worked timeline. The June revision describes the same economic period as the first release, but only the earlier available revision belongs to the decision snapshot. View full size ↗

Timestamp semantics

Field	Meaning
event_at	When the reported event or observation occurred.
published_at	When the source released this revision, if known.
received_at	When Seer first received this revision.
available_at	When the validated record became available to this workflow.
computed_at	When a derived artifact was produced.

Two temporal questions

Valid time identifies the period to which a fact applies; system time identifies when a revision became known to the platform. A March statistic revised in June still refers to March, but the June revision is absent from an April decision’s information set.

Seer replay selects revisions available to the workflow at the decision cutoff. A reconstruction based on source publication time is a different mode because source publication and platform receipt can differ. Unknown publication timestamps remain unknown rather than inheriting the current retrieval time.

Eligibility at a decision cutoff

Here t is the decision instant; rights represents the applicable access and use conditions. Eligibility must include transformation inputs and identity mappings, not just the final document timestamp. Incomplete vintage history prevents a complete point-in-time claim.

\operatorname{Eligible}(e,t)=\mathbf1[a_e\le t]\,\mathbf1[\operatorname{rights}(e)]\,\mathbf1[\operatorname{valid}(e)]

Evidence record

json

{
  "id": "ev_release_example",
  "revision": "1",
  "kind": "source_observation",
  "source_ref": "source:release:example",
  "instrument_id": null,
  "event_at": "2026-09-01T00:00:00Z",
  "published_at": "2026-10-01T12:30:00Z",
  "received_at": "2026-10-01T12:30:02Z",
  "available_at": "2026-10-01T12:30:03Z",
  "supersedes": null,
  "quality": {"revision_history": "incomplete"},
  "payload": {"value": "3.1", "unit": "percent"}
}

Lineage and transformations

Source observations, normalized records, features, forecasts and interpretations are distinct artifact types. A derived artifact references its input revisions and transformation revision, producing a directed acyclic provenance graph. Normalization retains source price types, units, currencies and session conventions.

Conflicting observations remain attributable instead of being overwritten by a consensus value. Ambiguous instrument mappings propagate an unresolved state to dependent calculations. Content digests identify payload changes; source authenticity and authorized access are recorded separately.

Ingestion and revisions

An ingestion checkpoint records accepted source items and revisions. Adapters validate schema and units, preserve quality flags and deduplicate repeated deliveries. Source latency, transport latency and transformation latency remain distinct measurements.

Backfill adds historical evidence with its actual receipt and availability times. It does not create a fictional historical observation stream. Superseded versions remain available according to the applicable retention rights; a source that exposes only its latest value has correspondingly limited revision coverage.

As-of selection on two time axes

v is the economic valid-time query; t is the system cutoff. [v−,v+) is the valid-time interval, [s−,s+) is the interval during which that revision is current in the system, and a is workflow availability time. Open-ended intervals use an unbounded upper endpoint. Rights and quality checks further restrict eligibility. The system interval records revision admission under the same availability convention used by replay. An unvalidated replacement does not displace the last eligible revision.

\operatorname{select}(e;v,t)=\mathbf1[v_e^-\le v<v_e^+]\,\mathbf1[s_e^-\le t<s_e^+]\,\mathbf1[a_e\le t]

Information filtration and causal closure

The information set I_t contains only evidence and transformation inputs eligible at cutoff t. As time advances, new observations can enter the set; a later correction changes subsequent decisions without rewriting an earlier decision’s snapshot. In probabilistic terms, these information sets define the filtration with respect to which a forecast is conditioned.

A derived feature is causally closed only when every ancestor in its provenance graph satisfies the same cutoff. A point-in-time document joined to today’s instrument mapping or a revised macroeconomic series still leaks later information. Snapshot construction consequently includes identity maps, corporate-action conventions and transformation revisions, not only raw publication dates.