Simulate a constellation

POST/simulate

Purpose

Propagates a constellation that already exists in the service and registers the result as a scenario. The response carries a scenario identifier; the timeline itself is retrieved through the scenario export endpoints rather than returned inline, because a full timeline is large.

Create the constellation first with POST /constellations/walker, or by importing one.

Request body

Parameter	Type	Unit	Default	Required	Description
`constellation_id`	string	n/a	—	Yes	Identifier returned when the constellation was created or imported.
`start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Scenario start epoch.
`duration_hours`	number	h	`6`	No	Length of the propagation window.
`step_seconds`	number	s	`60`	No	Fixed output step.
`propagation_model`	string	n/a	`two_body`	No	One of `two_body`, `j2`, `sgp4`, `numerical`, `ephemeris`. Note the underscore.
`include_eclipse`	boolean	n/a	`false`	No	Attach per-sample illumination, eclipse intervals, and CZML shadow shading to the scenario.
`force_model`	object	n/a	—	No	Numerical force-model configuration. Used only with `propagation_model: "numerical"`; defaults to zonal J4 with Dormand-Prince 5(4).
`sensor_cone_half_angle_deg`	number	deg	—	No	Draw nadir sensor cones of this half-angle in the CZML output.
`frame_precision`	string	n/a	`fast`	No	Frame-conversion fidelity. `fast` is GMST-only; `full` is IAU-76/FK5 with leap seconds and rotates SGP4 TEME output to GCRF.
`eop_file`	string	n/a	—	No	Server-local path to an IERS finals2000A.all Earth-orientation file, used with `frame_precision: "full"`. Omitted means graceful zero-EOP degradation.

Two naming traps. The field is propagation_model, not model, and unknown fields are ignored rather than rejected, so a misspelling silently yields the default rather than an error. The two-body value is spelled two_body with an underscore here, while the CLI flag uses two-body with a hyphen. Passing the CLI spelling to the API returns invalid_request.

Example request


curl -s -X POST http://127.0.0.1:8080/simulate \
  -H 'content-type: application/json' \
  -d '{
        "constellation_id": "demo",
        "start": "2026-01-01T00:00:00Z",
        "duration_hours": 6.0,
        "step_seconds": 60.0,
        "propagation_model": "two_body"
      }'

Example response


{
  "scenario_id": "scenario-demo",
  "status": "completed",
  "satellite_count": 60,
  "sample_count": 361,
  "czml_url": "/api/scenarios/scenario-demo/czml"
}

Response fields.
Parameter	Type	Unit	Default	Required	Description
`scenario_id`	string	n/a	—	Yes	Identifier used to retrieve exports from the scenario endpoints.
`status`	string	n/a	—	Yes	Terminal state of the run.
`satellite_count`	integer	count	—	Yes	Satellites propagated.
`sample_count`	integer	count	—	Yes	Timeline samples per satellite, inclusive of both endpoints.
`czml_url`	string	n/a	—	Yes	Relative path to the CZML export for this scenario.

Status codes

Status	Condition	Body format
200	Propagation completed and the scenario was registered	JSON result
400	Request was well formed but could not be honored: unknown propagation model, or a model the constellation cannot support	JSON error envelope
404	`constellation_id` does not exist in the service	JSON error envelope
422	Body could not be deserialized: malformed JSON, wrong field type, or a missing required field	Plain text

Deserialization failures return 422 with a plain-text body, not the JSON error envelope. A client that parses every error response as JSON will fail on exactly the errors a new integration hits most often.

Error body

Application-level errors use a consistent envelope with a machine-readable code and a human-readable message.


{
  "error": {
    "code": "not_found",
    "message": "constellation `nope` not found; generate it first"
  }
}

A model incompatible with the constellation reports which satellite failed and what it lacked:


{
  "error": {
    "code": "invalid_request",
    "message": "propagation failed: satellite `demo-s0-p00-sat00` has no TLE; SGP4 propagation requires one (import via TLE)"
  }
}

Constellations live in the service’s own state. A 404 most often means the process was restarted, or the constellation was created against a different instance, rather than that the identifier was mistyped.