Skip to main content

Satellite and ground station telemetry API

Constellation takes one telemetry record per ground-to-satellite link: a time, the link's three IDs from your network config, and measured fields such as Es/N0, elevation and slant range. Everything else, fleet state, series reads and calibrated forecasts, is read from those records.

Three ways in​

PathUse it whenReference
POST /telemetry over HTTPSA backend or script sends batches, up to 1,000 records per requestTelemetry
gRPC TelemetryIngest.WriteA high-rate producer, with a live key that has telemetry:writegRPC ingest
The fleet agentApplications on your hosts publish to a local socket; the agent buffers to disk and delivers, so they never hold the API keyFleet agent

Flown passes go in as a CSV with POST /telemetry/pass-logs, and files in any other format through telemetry files.

A record​

[
{
"time": "2026-11-10T12:00:00Z",
"ground_station_id": "gs-1",
"ground_antenna_id": "ant-1",
"satellite_id": "sat-1",
"fields": { "es_n0_db": 12.5, "elevation_deg": 45.0, "range_m": 1200000.0 }
}
]

Every ID must be in your latest network config, and every field is from a fixed list with a fixed type.

Reading it back​

  • GET /topology returns the newest value of each field per link within a freshness window.
  • Series reads return a link's records over a time range, raw or aggregated.
  • Stepping as_of_utc replays the fleet as it was known at each instant.

Why it matters for forecasts​

Link SNR learns each antenna from the records you send. Write one record per link at least once a minute while the link is in view, with es_n0_db, elevation_deg and range_m, and the forecast moves from a datasheet link budget toward what your link measures.

Common questions​

What happens when part of a telemetry batch is invalid?

The API answers 202 with the rejected records listed by index. Correct those records and resend only them, so accepted records are not written twice.

Can I send telemetry in my own format?

Yes. Files the API has no dedicated route for go to telemetry files, in any format under a source label you choose, over HTTPS or SFTP for large files.

Do I need telemetry to get forecasts?

Not for every model. Weather attenuation and Satellite demand need none. Link SNR forecasts from the link budget without it and learns from telemetry once it arrives.

Next: see what link telemetry looks like on the demo fleet, which loads two hours of it.