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.

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,
      "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,
      "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"
    }
  ]
}

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, command, and resource limits.

https://api.nodion.com/v1/runners/:runner_id/runs

Required Headers: Authorization

Optional Body Parameters:

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:

{
  "env_variables": [
    { "env_key": "BACKUP_TARGET", "env_val": "s3://my-bucket/backups" },
    { "env_key": "VERBOSE", "env_val": "true" }
  ]
}

Example Response:

{
  "run": {
    "id": "e5f6a7b8-c9d0-1234-efab-345678901234",
    "status": "pending",
    "exit_code": 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), or failed (completed with a non-zero exit code or timed out).