Skip to content

Observations

The Observation API covers everything observation-shaped: observations themselves, observation requests, observation tasks, and targets. It’s the API you’ll spend the most time in if you’re automating data acquisition.

The generated API reference is the authoritative source for every endpoint and field. The narrative here covers what isn’t obvious from the spec.

Resource What it is
/v1/observations Observations — the top-level container. See Observation schema
/v1/observation-requests Per-observation data requests (imaging, radio, calibrations). Polymorphic on requestType
/v1/observation-tasks Per-task execution records the scheduler creates from requests
/v1/targets Celestial targets — fixed, catalog, ephemeral, orbital positions
/v1/observations/{uid}/assets The frames and data products an observation produced

An observation is created in one POST /v1/users/{slug}/observations (or /v1/organizations/{slug}/observations) from a complete ObservationCreate — target, imaging configuration, requests, and funding grants all in one body. The observation is created active and visible to the scheduler immediately. Create it under the entity that owns the observing account behind its grants; every grant must belong to that owner. See Creating observations for the full walkthrough.

Lifecycle changes after creation:

Operation How
Cancel PATCH /v1/observations/{uid} with { "status": "canceled" } — drops pending tasks
Reopen a canceled observation PATCH /v1/observations/{uid} with { "status": "active" }
Flag as deleted PATCH /v1/observations/{uid} with { "isDeleted": true } (the observation list does not filter on this flag)
Delete DELETE /v1/observations/{uid} — refused once the observation has generated tasks (cancel instead)
Re-author from a spec POST /v1/observations/{uid}/apply-spec with { "spec": <spec envelope> } (export the current one with GET /v1/observations/{uid}/spec)
Add a target POST /v1/observations/{uid}/target — only when the observation has none; returns 400 if it already has a target
  • Polymorphic discrimination. Every request and task carries a requestType / taskType. When you create a request, the body shape depends on the discriminator. See Conventions → Polymorphic resources.
  • Targets are nested. A target attaches to an observation — set it in the create body (target), or afterward with POST /v1/observations/{uid}/target if it has none. Read it back with GET /v1/observations/{uid}/target, where the position appears as targetPosition. /v1/targets is read-mostly.
  • One POST, no drafts. An observation is created complete and active from a single ObservationCreate; there’s no draft/instance distinction and no publish step. Field names are camelCase but enum values are snake_case ("requestType": "optical_imaging"); set one exposure-sizing field per request (exposureTimeSec / targetSnr / targetFullWellFraction); and add instrumentMode: "include" if you list instrumentUids. See Creating observations.
  • Quota mechanics. Submitting an observation costs nothing. Credits are tallied against the funding account and grant as tasks dispatch (ObservingAccountTxn records). Throttling is driven by quotas attached to accounts and grants — each quota is a (period_type, max_credits) rule; period types are lifetime, day, week, month, or night. Multiple quotas can attach to the same account / grant and all must be satisfied; dispatch pauses when any one would be exceeded. Quota-exceeded observations stall rather than error, and resume as quota frees up. See Observing accounts → Quotas.

The curl quickstart walks the most common flow (find a grant + imager → POST the observation → poll), and Creating observations covers catalog/non-sidereal targets and asset download.

Other recipes worth knowing:

  • Submit from an existing project template — use POST /v1/project-templates/{uid}/instantiate instead of building the spec by hand. See Project templates.
  • Bulk submission — submit observations one at a time today; there’s no bulk endpoint. Wrap the per-observation calls with your own retry logic.
  • Watch for completion — poll GET /v1/observations/{uid} (or /progress) for status: completed, or subscribe to the observation_event stream via WebSocket for push updates.