Topology

GET /topology answers "what is the latest known state of every entity in my fleet?" It projects your ingested telemetry into one row per entity: for each entity, the newest sample inside a freshness window ending at a chosen instant. The console globe, the fleet agent, and your own pollers all read the same projection.

GET /topology

Auth: x-api-key. See Authentication.

Query parameters

Parameter	Type	Default	Description
`as_of_utc`	ISO 8601 datetime	now	The instant to evaluate. The window of samples considered ends here.
`measurement`	string	all allowlisted	Restrict to one measurement. Must be one of `link`, `satellite`, `ground_station`, `weather`, `telemetry`; anything else is `400 invalid_input`.
`freshness_seconds`	float, 1 to 604800	server default	Look-back window. Only samples within `freshness_seconds` before `as_of_utc` are considered.

Semantics

Latest-per-entity. For each entity that has at least one sample inside the window, you get exactly one row: its newest sample. Entities silent for longer than the window simply disappear from the response; treat absence as "stale", not "deleted".
Row cap. Reads scan at most 50,000 rows per query. A very wide window over a chatty fleet can hit the cap and yield an incomplete projection. Keep freshness_seconds as tight as your ingest cadence allows, or split queries by measurement.
No pagination. There is no cursor or offset. The freshness window and the measurement filter are your only sizing tools.

Response

{
  "as_of_utc": "2026-07-09T14:32:00Z",
  "tenant_key": "acme-sat",
  "entities": [
    {
      "measurement": "satellite",
      "entity_id": "SAT-0012",
      "observed_at": "2026-07-09T14:31:42Z",
      "tags": { "node_id": "SAT-0012", "node_type": "satellite" },
      "fields": { "lat": 47.61, "lon": -122.33, "altitude_km": 550.2, "utilization": 0.42 }
    },
    {
      "measurement": "ground_station",
      "entity_id": "GS-SEA-01",
      "observed_at": "2026-07-09T14:31:55Z",
      "tags": { "node_id": "GS-SEA-01", "node_type": "ground_station" },
      "fields": { "lat": 47.44, "lon": -122.3, "utilization": 0.61 }
    }
  ]
}

Field	Description
`as_of_utc`	The evaluation instant (echoes your parameter, or now).
`tenant_key`	Your tenant, resolved from the API key.
`entities[].measurement`	Which measurement the row came from.
`entities[].entity_id`	Stable entity identifier.
`entities[].observed_at`	Timestamp of the newest sample for this entity.
`entities[].tags`	String tags as ingested (for example `node_id`, `node_type`).
`entities[].fields`	Numeric or string values as ingested.

Example

curl -sS \
  -H "x-api-key: $CONSTELLATION_API_TOKEN" \
  "https://api.constellation.space/topology?measurement=satellite&freshness_seconds=900&as_of_utc=2026-07-09T14:32:00Z"

Replay: stepping `as_of_utc`

Because the projection is evaluated at an arbitrary instant, historical replay is just a loop: step as_of_utc through a time range at a fixed interval and issue one request per step. Each response is the fleet as it was known at that instant.

for t in 2026-07-09T12:00:00Z 2026-07-09T12:05:00Z 2026-07-09T12:10:00Z; do
  curl -sS -H "x-api-key: $CONSTELLATION_API_TOKEN" \
    "https://api.constellation.space/topology?measurement=satellite&freshness_seconds=300&as_of_utc=${t}"
done

Match freshness_seconds to your step so consecutive frames do not smear stale entities forward. Budget replay loops against the rate limits (60 requests/minute per tenant); a runnable poller is in Poll topology.

Errors

Status	Body	Cause
`400`	`{"error": "invalid_input", "field": "entity_type"}`	`measurement` outside the allowlist.
`422`	`detail` list	Unparseable `as_of_utc` or `freshness_seconds` out of the 1 to 604800 range.
`401` / `403` / `404`	see Authentication	Key or tenant problems.
`429`	`rate_limited` or `auth_lockout`	Rate limits; honor `Retry-After`.
`503`	`{"error": "telemetry_unavailable", "upstream": "influx", "retry_after_seconds": 5}`	Time-series backend transient; retry after the delay.

Ingest telemetry: what feeds this projection.
Poll topology example: a stepped as_of_utc poller in four languages.
Integration patterns: polling cadences and freshness windows.

Query parameters​

Semantics​

Response​

Example​

Replay: stepping as_of_utc​

Errors​

Related​