---
title: "The values, each with provenance; envelope carries verification, license, citation, honest hasMore."
method: GET
path: "/v1/sources/{source}/series/{seriesId}/observations"
---

# The values, each with provenance; envelope carries verification, license, citation, honest hasMore.

`GET /v1/sources/{source}/series/{seriesId}/observations`

## Request

- Base URL: `https://starwell.dev/api/starwell`
- URL: `https://starwell.dev/api/starwell/v1/sources/{source}/series/{seriesId}/observations`
- Auth: one of:
  - HTTP bearer
  - none

## Path parameters

- `source` string, required
- `seriesId` string, required

## Query parameters

- `start` string, date
- `end` string, date
- `latest` integer
- `limit` integer
- `offset` integer
- `format` 'json' | 'csv'
- `asOf` string

## Response `200`

OK

- object
  - `success` true, required
  - `data` Observation[], required
    - `period` string, date, required
    - `value` number, nullable, required: Null only when status explains it.
    - `status` 'normal' | 'missing' | 'suppressed' | 'terminated'
    - `decimals` integer, nullable
    - `revision` integer: Bumps when the source revises the period; history is append-only.
    - `provenance` Provenance, required: Where this exact value came from — stored append-only, never inferred.
      - `sourceUrl` string, required: The exact source API request or table URL.
      - `retrievedAt` string, date-time, required
      - `connectorVersion` string, required
      - `releaseTime` string, date-time, nullable
      - `storedAt` string, date-time: asOf reads and /revisions only: when Starwell's store inserted this row (database-assigned, immutable) — the clock a point-in-time read keys on.
    - `revisedSince` boolean: asOf reads only: true when this period has been revised since the cutoff (the current value differs).
  - `meta` object
    - `series` object
    - `verification` Verification
      - `status` 'passing' | 'stale' | 'failing' | 'unverified', required: passing: golden-value + freshness checks pass against the live source. stale: newer official data exists (or the source has not been re-checked within its cadence window). failing: a golden check disagrees with the source — do not rely on it. unverified: not yet through the harness.
      - `lastVerifiedAt` string, date-time, nullable
    - `license` License
      - `code` 'public-domain' | 'statcan-open' | 'cc-by-4.0' | 'open-government' | 'third-party-restricted' | 'unknown'
      - `url` string, nullable
      - `attribution` string, nullable: The exact attribution line to print alongside the data.
      - `redistributable` boolean
      - `trainingEligible` boolean
    - `citation` Citation
      - `source` string
      - `authority` string, nullable
      - `dataset` string
      - `datasetExternalId` string
      - `url` string, nullable: Human-facing official table page.
      - `termsUrl` string, nullable
      - `text` string: Ready-to-print citation line.
    - `returned` integer: Rows in THIS response.
    - `offset` integer: The offset this page starts at; absent in latest=N mode.
    - `hasMore` boolean: True when rows exist past this page — fetch them with offset = offset + the number of rows returned here.
    - `asOf` object: Present only on asOf reads.
      - `requested` string: The asOf value as sent.
      - `cutoff` string, date-time: The instant applied (a bare date means the end of that UTC day, clamped to now).
      - `basis` 'store': Always 'store': the vintage is what Starwell's store held, keyed on the database-assigned insert time.
      - `firstIngestAt` string, date-time, nullable: When the store first held this series; no vintage exists before it.
      - `periodsRevisedSince` integer: Returned periods whose value has been revised since the cutoff.
      - `note` string: The claim boundary, in words.

## Other responses

- `400`: Invalid parameters.
- `404`: Unknown source, dataset, or series.
- `422`: asOf is earlier than the series' first ingest (code asof_before_first_ingest, with firstIngestAt). The store never answers a point-in-time ask with current values.
- `451`: The series exists but its license does not permit redistribution; no values are served.

---

[API](https://skmtc.dev/starwell/apis/starwell-api.md) · [All operations](https://skmtc.dev/starwell/apis/starwell-api/llms.txt) · [OpenAPI document](https://skmtc.dev/starwell/apis/starwell-api/revisions/faaa9f35d4e6?raw)