Scenarios

GET/scenarios/{id}

GET/scenarios/{id}/czml

GET/scenarios/{id}/oem

GET/scenarios/{id}/ephemeris.csv

GET/scenarios/{id}/contacts.csv

Purpose

A scenario is a completed propagation, registered when POST /simulate or an analysis endpoint runs. These endpoints retrieve its metadata and export the timeline in the format your downstream tool expects.

The timeline is not returned inline by the endpoint that creates it, because a full timeline is large. You get an identifier and fetch what you need.

`GET /scenarios/{id}`

Returns scenario metadata: what was run, how, and how much of it there is.


curl -s http://127.0.0.1:8080/scenarios/scenario-demo


{
  "scenario_id": "scenario-demo",
  "name": "demo",
  "start_time": "2026-01-01T00:00:00Z",
  "duration_seconds": 21600.0,
  "step_seconds": 60.0,
  "model": "two_body",
  "satellite_count": 60,
  "sample_count": 361
}

This is the provenance record. Frame, epoch, step, and model together are what make a result reproducible and auditable months later. Fetch it alongside any export you intend to keep.

Export formats

Endpoint	Format	Use
`/czml`	CZML	Time-dynamic scene for the CesiumJS viewer
`/oem`	CCSDS OEM, KVN	Ephemeris interchange with other flight-dynamics tools
`/ephemeris.csv`	CSV	Analysis in a spreadsheet or a data frame
`/contacts.csv`	CSV	Access intervals, for scheduling


curl -s http://127.0.0.1:8080/scenarios/scenario-demo/czml   > demo.czml
curl -s http://127.0.0.1:8080/scenarios/scenario-demo/oem    > demo.oem
curl -s http://127.0.0.1:8080/scenarios/scenario-demo/ephemeris.csv > ephem.csv
curl -s http://127.0.0.1:8080/scenarios/scenario-demo/contacts.csv  > contacts.csv

Choosing between them

CZML is a visualization format. It describes a scene over time and is what the globe viewer consumes; it is not a precise interchange format and should not be used to hand a trajectory to another flight-dynamics tool.

CCSDS OEM is the interchange format. It carries state vectors with declared frame, time system, and interpolation method, which is what another organization needs to reproduce your trajectory rather than approximate it.

Scenario identifiers

Identifiers are derived from the operation that created them, not randomly allocated:

Created by	Identifier
`POST /simulate` on constellation `demo`	`scenario-demo`
`POST /link` on constellation `demo`	`link-demo`

That is convenient and has a consequence: re-running the same operation on the same constellation reuses the identifier, replacing the previous scenario. There is no history. If you need to keep a result, export it.

A link run additionally returns a run_id such as link-demo-2026-08-13T18:08:53Z-0000, which does distinguish successive runs even though the scenario identifier does not.

Errors

Status	Condition
200	Scenario found
404	No scenario with that identifier


{
  "error": {
    "code": "not_found",
    "message": "scenario `nope` not found"
  }
}

Scenarios are held in memory. A 404 on an identifier you just created means the service restarted, or you are addressing a different instance, far more often than it means a typo.