Runs · Stellar Control

GET/v1/runs

List runs#

Recent runs

The most recent runs, newest first, with their state computed from their logs.

Query parameters

limit

integer

How many runs: 20 by default, 200 at most.

≥ 0

Responses

200Runs, newest first.application/json

runsrequired

array of RunSummary

Runs, newest first.

RunSummary · 12 fields

runrequired

string

Run.

procedurerequired

string

Procedure.

step

string

Step running or last run.

suspendedrequired

boolean

Whether it is suspended.

pending

one of Pending | null

finished

boolean

Outcome, once finished.

reason

string

Why it failed.

environmentrequired

string

Environment.

targetsrequired

map of string

Target of each role.

by

string

Who launched it.

started_at

string · date-time

Start.

updated_at

string · date-time

Last event.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/runs"

import requests

BASE_URL = "http://localhost:8080"

response = requests.get(f"{BASE_URL}/v1/runs")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/runs"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "runs": [
    {
      "run": "string",
      "procedure": "string",
      "step": "string",
      "suspended": true,
      "pending": null,
      "finished": true,
      "reason": "string",
      "environment": "string",
      "targets": {
        "key": "string"
      },
      "by": "string",
      "started_at": "2026-09-29T08:30:00Z",
      "updated_at": "2026-09-29T08:30:00Z"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/runs

Launch run#

Launch a run

Resolves the run request against the current configuration into a self-contained resolved run, stores it in stellar_ir and submits it to the executor. The environment applies its policies: allowed procedures, draft packages, identity, hazardous telecommands only from a schedule where planning is mandatory. A run bound to a pass (plan) must start within it and fit before its LOS minus scheduler.margin; a manual run in in_orbit needs an available link.

Request body application/jsonrequired

runrequired

string

Procedure.

library

string

Library of the procedure, when several have a procedure of that name.

environmentrequired

string

Environment.

targetsrequired

map of string

Target of each role.

inputs

map of InputArg

Input values.

plan

string

Pass the run is planned on, set by the scheduler.

faults

array of FaultRequest

Faults of the simulations to switch on during the run: simulated targets only.

FaultRequest · 4 fields

targetrequired

string

Role of the target, as in targets.

faultrequired

string

Fault, as the simulation of the target names it.

at

Trigger

When it is switched on: after the start of the run, or of the first entry in a step.

Trigger · 2 fields

step

string

Step whose first entry starts the delay: its name (Plateau), or its path (TVAC cycle / Plateau).

after

string

Delay.

off

one of Trigger | null

Responses

202Submitted: follow it on GET /v1/runs/{id}/events. warnings names the passes in progress it may outlast.application/json

runrequired

string

Identifier of the run.

irrequired

string

Hash of the resolved run in stellar_ir.

warnings

array of string

What the operator should know: a run that may end after the LOS of the pass in progress.

400Invalid body: api::invalid-body.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

401Identity required by the environment: api::anonymous, auth::jwt-required, auth::invalid-token.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409Refused by the passes: run::pass-cancelled, run::not-booked, run::before-aos, run::window, run::receive-only, run::no-link.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

422The request does not resolve, or breaks a policy: run::not-allowed, run::draft-not-allowed, run::plan-required, run::must-be-scheduled, run::unknown-pass, run::link-component…application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/runs" \
  -H "Content-Type: application/json" \
  -d '{
  "run": "string",
  "library": "string",
  "environment": "string",
  "targets": {
    "key": "string"
  },
  "inputs": {
    "key": true
  },
  "plan": "string",
  "faults": [
    {
      "target": "string",
      "fault": "string",
      "at": {
        "step": "string",
        "after": "string"
      },
      "off": {
        "step": "string",
        "after": "string"
      }
    }
  ]
}'

import requests

BASE_URL = "http://localhost:8080"

response = requests.post(
    f"{BASE_URL}/v1/runs",
    json={
        "run": "string",
        "library": "string",
        "environment": "string",
        "targets": {
            "key": "string",
        },
        "inputs": {
            "key": True,
        },
        "plan": "string",
        "faults": [
            {
                "target": "string",
                "fault": "string",
                "at": {
                    "step": "string",
                    "after": "string",
                },
                "off": {
                    "step": "string",
                    "after": "string",
                },
            },
        ],
    },
)
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/runs"))
    .json(&serde_json::json!({
      "run": "string",
      "library": "string",
      "environment": "string",
      "targets": {
        "key": "string"
      },
      "inputs": {
        "key": true
      },
      "plan": "string",
      "faults": [
        {
          "target": "string",
          "fault": "string",
          "at": {
            "step": "string",
            "after": "string"
          },
          "off": {
            "step": "string",
            "after": "string"
          }
        }
      ]
    }))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "run": "string",
  "ir": "string",
  "warnings": [
    "string"
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/runs/{id}

Run status#

State of a run

Computed from its log: step running, suspended, question or decision waiting (with the role awaited for a hazardous confirmation), outcome.

Path parameters

idrequired

string

Run identifier (ULID).

Responses

200State of the run.application/json

runrequired

string

Run.

procedurerequired

string

Procedure.

step

string

Step running or last run.

suspendedrequired

boolean

Whether it is suspended.

pending

one of Pending | null

finished

boolean

Outcome, once finished.

reason

string

Why it failed.

404Invalid identifier or no such run: run::unknown.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/runs/<id>"

import requests

BASE_URL = "http://localhost:8080"
id = "<id>"  # Run identifier (ULID).

response = requests.get(f"{BASE_URL}/v1/runs/{id}")
response.raise_for_status()
print(response.json())

let base_url = "http://localhost:8080";
let id = "<id>"; // Run identifier (ULID).

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/runs/{id}"))
    .send()
    .await?
    .error_for_status()?;
let body: serde_json::Value = response.json().await?;
println!("{body:#}");

Response

{
  "run": "string",
  "procedure": "string",
  "step": "string",
  "suspended": true,
  "pending": {
    "path": "string",
    "kind": "string",
    "prompt": "string",
    "role": "string"
  },
  "finished": true,
  "reason": "string"
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/runs/{id}/events

Follow run#

Follow a run (WebSocket)

Replays the log of the run, then follows it until its finished event. Each message is a RunEvent.

Path parameters

idrequired

string

Run identifier (ULID).

Responses

101WebSocket: one RunEvent per message.application/json

atrequired

string

Time of the event.

runrequired

string

Run.

seqrequired

integer · uint64

Position in the log, from 1.

≥ 0

404Invalid identifier.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/runs/<id>/events"

import requests

BASE_URL = "http://localhost:8080"
id = "<id>"  # Run identifier (ULID).

response = requests.get(f"{BASE_URL}/v1/runs/{id}/events")
response.raise_for_status()

let base_url = "http://localhost:8080";
let id = "<id>"; // Run identifier (ULID).

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/runs/{id}/events"))
    .send()
    .await?
    .error_for_status()?;

Response

{
  "by": "string",
  "environment": "string",
  "event": "started",
  "inputs": {},
  "ir": "string",
  "library": "string",
  "procedure": "string",
  "targets": {
    "key": "string"
  }
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/runs/{id}/answers

Answer run#

Answer a question or a decision

Answers the ask of a step (a confirmation, or a typed value) or a decision (replay, skip, fail or abort in value), as the operator identified by the request. The executor checks the answer: role expected, a person who has not confirmed the step yet, token checked again with identity: jwt; a refused answer is logged as answer_refused.

Path parameters

idrequired

string

Run identifier (ULID).

Request body application/jsonrequired

pathrequired

string

Step asking, as in its asked or decision_required event.

acceptedrequired

boolean

Whether the operator confirms.

value

any

Typed answer, or decision: replay, skip, fail or abort.

Responses

202Answer published to the executor.

400Invalid body, or no identity: api::invalid-body, api::anonymous.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

401Identity refused by the environment of the run.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Invalid identifier or no such run.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/runs/<id>/answers" \
  -H "Content-Type: application/json" \
  -d '{
  "path": "string",
  "accepted": true,
  "value": null
}' \
  -o response.bin

import requests

BASE_URL = "http://localhost:8080"
id = "<id>"  # Run identifier (ULID).

response = requests.post(
    f"{BASE_URL}/v1/runs/{id}/answers",
    json={
        "path": "string",
        "accepted": True,
        "value": None,
    },
)
response.raise_for_status()
data = response.content

let base_url = "http://localhost:8080";
let id = "<id>"; // Run identifier (ULID).

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/runs/{id}/answers"))
    .json(&serde_json::json!({
      "path": "string",
      "accepted": true,
      "value": null
    }))
    .send()
    .await?
    .error_for_status()?;
let bytes = response.bytes().await?;

Response

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

POST/v1/runs/{id}/{action}

Control run#

Suspend, resume or abort a run

suspend takes effect at the end of the current instruction and releases the leases of the run; resume takes them back, checks the targets again and applies the choice of the operator (replay the step where the run stopped, skip it, or abort); abort ends the run for good, without its if failed blocks. The command goes to the executor holding the run.

Path parameters

idrequired

string

Run identifier (ULID).

actionrequired

string

suspend, resume or abort.

Request body application/json

For resume only: the choice of the operator.

one of Resume | null

Responses

202Command accepted by the executor.

400Invalid body, or no identity.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

404Invalid identifier, or unknown command: api::unknown-command.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

409The run is not running (run::not-running) or the executor refused the command (run::refused).application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

504The executor did not answer: run::timeout.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl -X POST "http://localhost:8080/v1/runs/<id>/<action>" \
  -H "Content-Type: application/json" \
  -d '{
  "choice": "string"
}' \
  -o response.bin

import requests

BASE_URL = "http://localhost:8080"
id = "<id>"  # Run identifier (ULID).
action = "<action>"  # `suspend`, `resume` or `abort`.

response = requests.post(
    f"{BASE_URL}/v1/runs/{id}/{action}",
    json={
        "choice": "string",
    },
)
response.raise_for_status()
data = response.content

let base_url = "http://localhost:8080";
let id = "<id>"; // Run identifier (ULID).
let action = "<action>"; // `suspend`, `resume` or `abort`.

let response = reqwest::Client::new()
    .post(format!("{base_url}/v1/runs/{id}/{action}"))
    .json(&serde_json::json!({
      "choice": "string"
    }))
    .send()
    .await?
    .error_for_status()?;
let bytes = response.bytes().await?;

Response

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

GET/v1/runs/{id}/report

Run report#

Test report of a run

The HTML report archived at the end of the run (stellar_reports), else rendered from its log so far. The same log always gives the same report.

Path parameters

idrequired

string

Run identifier (ULID).

Responses

200The report.text/html

string

404Invalid identifier or no such run.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

503The MCS bus (NATS) is unavailable: api::unavailable.application/json

errorsrequired

array of ErrorItem

Every error found.

ErrorItem · 3 fields

coderequired

string

Stable code.

messagerequired

string

Message for the operator.

help

string

Suggested fix.

Request

curl "http://localhost:8080/v1/runs/<id>/report" \
  -o response.bin

import requests

BASE_URL = "http://localhost:8080"
id = "<id>"  # Run identifier (ULID).

response = requests.get(f"{BASE_URL}/v1/runs/{id}/report")
response.raise_for_status()
data = response.content

let base_url = "http://localhost:8080";
let id = "<id>"; // Run identifier (ULID).

let response = reqwest::Client::new()
    .get(format!("{base_url}/v1/runs/{id}/report"))
    .send()
    .await?
    .error_for_status()?;
let bytes = response.bytes().await?;

Response

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "message": "string",
      "help": "string"
    }
  ]
}