Runner Runs API Endpoints
Trigger and monitor individual runs of your runners with our API
Each run represents a single execution of a runner's container. When you trigger a run, the specified Docker image is pulled, the run command is executed, and logs are captured. You can optionally pass environment variables that override the runner's defaults for that specific run.
Contents
Get Runs
To list all runs of a runner you can simply send a GET request to the following endpoint.
https://api.nodion.com/v1/runners/:runner_id/runs
Required Headers: Authorization
Example Response:
{
"runs": [
{
"id": "c3f85434-5470-46de-bbeb-ce668ca2c351",
"status": "succeeded",
"exit_code": 0,
"command": null,
"argv": ["python", "migrate.py", "--env", "staging"],
"entrypoint": null,
"started_at": "2026-01-15T10:01:00.000+01:00",
"completed_at": "2026-01-15T10:05:30.000+01:00",
"created_at": "2026-01-15T10:00:55.000+01:00",
"updated_at": "2026-01-15T10:05:30.000+01:00"
},
{
"id": "d4e5f6a7-b8c9-0123-defa-234567890123",
"status": "failed",
"exit_code": 1,
"command": null,
"argv": [],
"entrypoint": null,
"started_at": "2026-01-14T08:00:00.000+01:00",
"completed_at": "2026-01-14T08:02:15.000+01:00",
"created_at": "2026-01-14T07:59:50.000+01:00",
"updated_at": "2026-01-14T08:02:15.000+01:00"
}
]
} Get Run
To fetch a single run you can simply send a GET request to the following endpoint. This is useful for polling the status of a run after triggering it.
https://api.nodion.com/v1/runners/:runner_id/runs/:id
Required Headers: Authorization
Example Response:
{
"run": {
"id": "c3f85434-5470-46de-bbeb-ce668ca2c351",
"status": "succeeded",
"exit_code": 0,
"command": "python migrate.py --env=staging",
"argv": [],
"entrypoint": null,
"started_at": "2026-01-15T10:01:00.000+01:00",
"completed_at": "2026-01-15T10:05:30.000+01:00",
"created_at": "2026-01-15T10:00:55.000+01:00",
"updated_at": "2026-01-15T10:05:30.000+01:00"
}
} Trigger a new Run
To trigger a new run of a runner you can simply send a POST request to the following endpoint. The run will be queued and executed asynchronously. The container will be started with the runner's configured image and resource limits, optionally with a per-run command, argv, entrypoint, or environment variable overrides.
https://api.nodion.com/v1/runners/:runner_id/runs
Required Headers: Authorization
Optional Body Parameters:
You may provide argv or command, not both. If neither is set, the runner's defaults apply.
argv – An array of strings executed in exec form, without a shell wrap. Overrides the runner's default for this run only. Recommended for SDKs, automation and AI agents. Example: ["python", "migrate.py", "--env", "staging"]. Max 200 elements, total length max 8000 characters.
command – A single shell command executed via sh -c. Overrides the runner's default run_command for this run only. Up to 4000 characters. Use this when you need shell features like &&, pipes or variable interpolation.
entrypoint – Overrides the runner's default entrypoint for this run only. Up to 500 characters.
env_variables – An array of environment variable objects to pass to this run. Each object must contain env_key and env_val. These override the runner's default environment variables for this run only.
Possible Response Codes:
200 – The run was triggered successfully.
400 – There was something wrong. Please check the response.
Example Request Body (argv, recommended):
{
"argv": ["python", "migrate.py", "--env", "staging"],
"env_variables": [
{ "env_key": "BACKUP_TARGET", "env_val": "s3://my-bucket/backups" },
{ "env_key": "VERBOSE", "env_val": "true" }
]
} Example Request Body (shell command):
{
"command": "cd /app && python migrate.py | tee /var/log/out.log",
"env_variables": [
{ "env_key": "VERBOSE", "env_val": "true" }
]
} Example Response:
{
"run": {
"id": "e5f6a7b8-c9d0-1234-efab-345678901234",
"status": "pending",
"exit_code": null,
"command": null,
"argv": ["python", "migrate.py", "--env", "staging"],
"entrypoint": null,
"started_at": null,
"completed_at": null,
"created_at": "2026-01-15T12:00:00.000+01:00",
"updated_at": "2026-01-15T12:00:00.000+01:00"
}
} A run goes through the following statuses: pending (queued for execution), running (currently executing), succeeded (completed with exit code 0), failed (completed with a non-zero exit code or timed out), or canceled (stopped by the user before completion).
Stop a Run
To cancel a pending or running run send a POST request to the following endpoint. Nodion marks the run as canceled, removes the container and cleans up any uploaded files on the hypervisor. Runs that have already finished are returned unchanged.
https://api.nodion.com/v1/runners/:runner_id/runs/:id/stop
Required Headers: Authorization
Possible Response Codes:
200 – The run was canceled (or was already terminal).
400 – There was something wrong. Please check the response.
Example Response:
{
"run": {
"id": "e5f6a7b8-c9d0-1234-efab-345678901234",
"status": "canceled",
"exit_code": null,
"command": null,
"argv": [],
"entrypoint": null,
"started_at": "2026-01-15T12:00:05.000+01:00",
"completed_at": "2026-01-15T12:00:42.000+01:00",
"created_at": "2026-01-15T12:00:00.000+01:00",
"updated_at": "2026-01-15T12:00:42.000+01:00"
}
} Get Logs
To fetch the captured log lines of a run send a GET request to the following endpoint. The response is paginated, oldest line first. Only public log lines are returned. Internal lines produced by Nodion (for example container registry login output) are kept private.
https://api.nodion.com/v1/runners/:runner_id/runs/:run_id/logs
Required Headers: Authorization
Optional Query Parameters:
after_id – The id of the last log line you already have. Only log lines created after this entry are returned, which makes it easy to poll for incremental updates.
Example Response:
{
"logs": [
{
"id": "1a2b3c4d-5e6f-7890-abcd-1234567890ab",
"body": "Pulling mycompany/backup-tool:latest",
"log_level": "log_public",
"created_at": "2026-01-15T10:01:00.123+01:00",
"updated_at": "2026-01-15T10:01:00.123+01:00"
},
{
"id": "2b3c4d5e-6f70-8901-bcde-2345678901bc",
"body": "========> Executing command",
"log_level": "log_public",
"created_at": "2026-01-15T10:01:05.456+01:00",
"updated_at": "2026-01-15T10:01:05.456+01:00"
}
]
} Stream Logs
To follow a run's logs live, open a Server-Sent Events stream to the following endpoint. Each log line arrives as a log event as soon as it is written. When the run reaches a terminal status the stream sends one final state event with the run's status and exit code, then closes.
https://api.nodion.com/v1/runners/:runner_id/runs/:run_id/logs/stream
Required Headers: Authorization, Accept: text/event-stream
Optional Query Parameters:
after_id – Resume the stream after a known log entry. Useful for reconnecting without missing or duplicating lines.
Events:
log– A single log line. Payload:{ "id", "body", "log_level", "created_at" }.state– The run's terminal status. Sent once just before the stream closes. Payload:{ "status", "exit_code", "started_at", "completed_at" }.error– An unexpected stream error. Payload:{ "error" }.
The server also emits SSE comment lines (: ping) every 15 seconds to keep the connection alive through intermediate proxies.
Example Stream:
event: log
data: {"id":"1a2b3c4d-5e6f-7890-abcd-1234567890ab","body":"Pulling mycompany/backup-tool:latest","log_level":"log_public","created_at":"2026-01-15T10:01:00.123+01:00"}
event: log
data: {"id":"2b3c4d5e-6f70-8901-bcde-2345678901bc","body":"========> Executing command","log_level":"log_public","created_at":"2026-01-15T10:01:05.456+01:00"}
: ping
event: state
data: {"status":"succeeded","exit_code":0,"started_at":"2026-01-15T10:01:00.000+01:00","completed_at":"2026-01-15T10:05:30.000+01:00"}