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.
Endpoints at a glance
Section titled “Endpoints at a glance”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 |
Creating and changing observations
Section titled “Creating and changing observations”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 |
Common pitfalls
Section titled “Common pitfalls”- 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 withPOST /v1/observations/{uid}/targetif it has none. Read it back withGET /v1/observations/{uid}/target, where the position appears astargetPosition./v1/targetsis 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 addinstrumentMode: "include"if you listinstrumentUids. See Creating observations. - Quota mechanics. Submitting an observation costs nothing. Credits are tallied against the funding account and grant as tasks dispatch (
ObservingAccountTxnrecords). Throttling is driven by quotas attached to accounts and grants — each quota is a(period_type, max_credits)rule; period types arelifetime,day,week,month, ornight. 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.
Common task recipes
Section titled “Common task recipes”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}/instantiateinstead 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) forstatus: completed, or subscribe to theobservation_eventstream via WebSocket for push updates.