Skip to content

Creating observations

This guide shows how to submit observations programmatically — resolve a target, build the request, pin it to a telescope, and retrieve the resulting frames — for both sidereal targets (deep-sky objects) and non-sidereal targets (asteroids, comets, satellites) under rate tracking.

It assumes you’ve read Authentication and Conventions. The web observation editor submits the same content (as a spec envelope through POST /v1/observation-specs:publish) — this guide is its programmatic equivalent.

A single POST creates the whole observation. One ObservationCreate body bundles four things:

graph LR
  O["Observation"] --> T["Target<br/>what to point at"]
  O --> C["OpticalImagingConfiguration<br/>tracking + brightness models"]
  O --> R["requests<br/>filter + exposure per pass"]
  O --> G["Funding<br/>observingGrantUids"]
  O --> I["Instruments<br/>instrumentMode + instrumentUids"]
  • Target — a name plus a position (a catalog object, fixed coordinates, or a full orbit).
  • Configuration — trackingMode (sidereal or target), dithering, and the brightness/saturation models that size exposures.
  • Requests — one or more exposure passes (filter + exposure spec + repeat count).
  • Funding — the observing grant(s) that pay for it, which decide the telescopes it can run on, and optionally the instrument(s) to restrict it to (instrumentMode: "include" + instrumentUids).

Any HTTP client works: the wire format is plain JSON. The examples use httpx in Python, built-in fetch in TypeScript (Node 20+), and curl with jq.

import os, httpx
client = httpx.Client(
base_url="https://api.skynetgo.org/v1",
headers={"Authorization": f"Bearer {os.environ['SKYNET_TOKEN']}"},
timeout=30.0,
)

For typed models, generate them from the OpenAPI document (see Quickstart: Python and Quickstart: TypeScript).

You need an observing grant that funds the telescope, that telescope’s imager, and the filter specifiers you want. You do not send an owner: you create the observation under the entity that owns the grant’s observing account (/users/{slug} or /organizations/{slug}), and the API rejects a grant from another owner’s account.

# Telescopes you can observe with; each embeds its instruments:
scopes = client.get("/me/observing-access/telescopes").raise_for_status().json()
telescope = next(t for t in scopes if t["name"] == "<telescope-name>")
telescope_uid = telescope["uid"]
# The telescope's optical imager + its filters:
imager = next(i for i in telescope["instruments"] if i["instrumentType"] == "optical_imager")
instrument_uid = imager["uid"]
filter_specifiers = sorted({f for w in imager["filterWheels"]
for pos in w["positions"] for f in pos["filterIds"]})
# One of your grants that can fund this telescope, and the owner it belongs to:
grants = client.get("/me/observing-access/observing-grants",
params={"telescopeUid": telescope_uid}).raise_for_status().json()
grant_uid = grants[0]["uid"]
owner = grants[0]["account"]["owner"]
owner_path = f"/{'organizations' if owner['entityType'] == 'organization' else 'users'}/{owner['slug']}"

Keep the telescope’s uid, one grant’s uid and its owner, the imager’s uid, and the filter specifier(s) you want (e.g. "lum").

Named objects — asteroids, comets, satellites, solar-system bodies

Section titled “Named objects — asteroids, comets, satellites, solar-system bodies”

GET /catalog-objects/search?q= resolves a name, designation, or catalog number to a ready-to-submit position block (covering SIMBAD stars/DSOs, NORAD satellites with live TLEs, MPC orbits and comets, and major bodies).

hit = client.get("/catalog-objects/search", params={"q": "Eros"}).raise_for_status().json()[0]
position = hit["position"] # {"positionType": "catalog", "catalogObjectUid": "<uid>", ...}

GET /common-targets?latitudeDeg=&longitudeDeg= ranks visible DSOs (galaxies, nebulae, clusters) by brightness and hours-visible for a site, returning raDeg / decDeg you submit as a fixed position. Take the site from the telescope record you picked in Step 1 (publicLatitudeDeg / publicLongitudeDeg).

Terminal window
curl -s "${auth[@]}" "$SKYNET/common-targets?latitudeDeg=<site-latitude>&longitudeDeg=<site-longitude>" \
| jq '[.[] | {name, targetType, raDeg, decDeg, maxAlt: .observability[0].maxAltitude}]
| sort_by(-.maxAlt)[:10]'

POST /users/{slug}/observations or POST /organizations/{slug}/observations, for the owner of the grant’s account. The body below is the minimal valid shape; see the Observation, OpticalImagingConfiguration, and OpticalImagingRequest schemas for every field.

# --- pick ONE position ---
# (a) catalog object (asteroid / satellite), from Step 2:
position = {"positionType": "catalog", "catalogObjectUid": hit["position"]["catalogObjectUid"]}
# (b) fixed DSO:
# position = {"positionType": "fixed",
# "coordinates": {"coordinateType": "equatorial", "raDeg": 49.575, "decDeg": -66.5}}
body = {
"name": "Eros rate-track test",
"target": {"name": "Eros", "position": position},
"opticalImagingConfiguration": {
"trackingMode": "target", # 'target' for movers, 'sidereal' for DSOs
"ditherStrategy": "none",
"temporalOffsetSec": 0.0,
"maxTiles": 1,
"tileOverlap": 0.0,
# brightness/saturation models size exposures (required for SNR / well-depth):
"brightnessModel": {"modelType": "source", "magnitudeMag": 14.0, "filterId": "V"},
"saturationModel": {"modelType": "source", "magnitudeMag": 8.0, "filterId": "V"},
},
"requests": [{
"requestType": "optical_imaging",
"order": 0,
"filterSpecifierIds": ["lum"],
"exposureTimeSec": 10.0, # set ONE of: exposureTimeSec | targetSnr | targetFullWellFraction
"sampleCount": 3,
}],
"observingGrantUids": [grant_uid],
"instrumentMode": "include", # restrict to instrumentUids
"instrumentUids": [instrument_uid],
}
created = client.post(f"{owner_path}/observations", json=body).raise_for_status().json()
print("created observation", created["uid"])
Field Meaning
opticalImagingConfiguration.trackingMode sidereal for stars/DSOs; target for non-sidereal rate tracking of asteroids/comets/satellites.
repointingStrategy, temporalOffsetSec (on the config) repoint policy and lead-ahead offset for fast movers.
request exposure spec Set one of exposureTimeSec, targetSnr, targetFullWellFraction. SNR / well-depth need the config’s brightnessModel to size against.
observingGrantUids The grants that fund the observation; together they decide which telescopes it can run on. Every grant’s account must belong to the owner in the URL.
instrumentMode + instrumentUids include restricts the observation to the listed instruments (exclude rules them out). With the default none, instrumentUids is ignored. There’s no telescope field on the body: pin a telescope by including only its imager.
sampleCount, and the scheduling-policy fields on the body (epochCount, cadence*, copies*) How many frames per pass, and how passes repeat over time. Defaults give a single epoch, ASAP. See the scheduling guide.

Step 4 — Track progress and download results

Section titled “Step 4 — Track progress and download results”

Frames land as assets under the observation. Poll incrementally with createdAfter, transfer any that are still node-resident, then download.

Terminal window
OBS=<observation-uid>
# New frames since a cutoff (newest-first by default):
curl -s "${auth[@]}" "$SKYNET/observations/$OBS/assets?createdAfter=2026-06-28T00:00:00Z" \
| jq '.items[] | {uid, name: .file.name, role, transferState, qaStatus}'
# If transferState != "transferred", request it off the node, then poll the one asset:
curl -s "${auth[@]}" -X POST "$SKYNET/observations/$OBS/assets/<asset-uid>/request-transfer"
curl -s "${auth[@]}" "$SKYNET/observations/$OBS/assets/<asset-uid>" | jq '{transferState, copyStatus}'
# Download (redirects via /files/{uid}/data to a presigned storage URL; follow with -L):
curl -sL "${auth[@]}" "$SKYNET/observations/$OBS/assets/<asset-uid>/data" -o frame.fits

Useful asset filters: role / roleExclude, qaStatus / serverQaStatus, transferState, isTransferrable, name, taskUids. For realtime delivery instead of polling, subscribe over the WebSocket streams.