Run Sessions & Run Requests API | Product Documentation

Run Sessions represent diagnostic or remediation workflows triggered by users, alerts, or automation. Each Run Session contains one or more Run Requests — individual runbook executions against specific SLXs.

Run Sessions

List Run Sessions

Retrieve all run sessions in a workspace.


Method	`GET`
Path	`/api/v3/workspaces/{workspace_name}/runsessions`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number for pagination
`page-size`	integer	No	Number of results per page
`modified__lte`	string	No	Filter by last modified date (ISO 8601, less than or equal)
`runrequest__runbook__name`	string	No	Filter by runbook name

Response 200 OK

JSON

{
  "count": 25,
  "next": "https://app.runwhen.com/api/v3/workspaces/my-ws/runsessions?page=2",
  "previous": null,
  "results": [
    {
      "id": 123,
      "workspace": "my-workspace",
      "source": "user",
      "isActive": true,
      "createdAt": "2026-02-28T10:00:00Z",
      "updatedAt": "2026-02-28T10:05:00Z"
    }
  ]
}

Create Run Session

Create a new run session in a workspace.


Method	`POST`
Path	`/api/v3/workspaces/{workspace_name}/runsessions`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace

Request Body

JSON

{
  "source": "user"
}

Field	Type	Required	Description
`source`	string	Yes	Source of the run session. One of: `user`, `alert`, `slack`, `workflow`, `api`

Response 201 Created

Returns the newly created run session object.

Update Run Session

Add a new run request to an existing run session, or update session metadata.


Method	`PATCH`
Path	`/api/v3/workspaces/{workspace_name}/runsessions/{runsession_id}`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`runsession_id`	integer	The ID of the run session

Response 200 OK

Returns the updated run session object.

Get Run Session Issues

Retrieve issues associated with a specific run session.


Method	`GET`
Path	`/api/v3/workspaces/{workspace_name}/runsessions/{runsession_id}/issues`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`runsession_id`	integer	The ID of the run session

Response 200 OK

Returns a list of issues detected during this run session.

Get Run Session Issue Detail

Retrieve a specific issue from a run session.


Method	`GET`
Path	`/api/v3/workspaces/{workspace_name}/runsessions/{runsession_id}/issues/{issue_id}`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`runsession_id`	integer	The ID of the run session
`issue_id`	integer	The ID of the issue

Response 200 OK

Returns the full issue detail.

Update Run Session Issue

Update an issue within a run session.


Method	`PATCH`
Path	`/api/v3/workspaces/{workspace_name}/runsessions/{runsession_id}/issues/{issue_id}`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`runsession_id`	integer	The ID of the run session
`issue_id`	integer	The ID of the issue

Response 200 OK

Returns the updated issue object.

Run Requests

Start Run Request

Start execution of a runbook run request (triggers the runner).


Method	`POST`
Path	`/api/v3/workspaces/{workspace_name}/slxs/{slx_name}/runbook/runs/{runrequest_id}/start`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`slx_name`	string	The short name of the SLX
`runrequest_id`	integer	The ID of the run request

Response 200 OK

Returns the started run request with execution details.

Step Run Request

Advance a run request to the next step (for multi-step runbooks).


Method	`PATCH`
Path	`/api/v3/workspaces/{workspace_name}/slxs/{slx_name}/runbook/runs/{runrequest_id}`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`slx_name`	string	The short name of the SLX
`runrequest_id`	integer	The ID of the run request

Response 200 OK

Returns the updated run request with current step information.

Get Run Request Status

Check the runner-side execution status of a run request.


Method	`GET`
Path	`/api/v3/workspaces/{workspace_name}/slxs/{slx_name}/runbook/runs/{runrequest_id}/runner-status`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`slx_name`	string	The short name of the SLX
`runrequest_id`	integer	The ID of the run request

Response 200 OK

Returns the current execution status from the runner.

Mark Run Request Failed

Manually mark a run request as failed.


Method	`PUT`
Path	`/api/v3/workspaces/{workspace_name}/runsessions/{runsession_id}/runrequests/{runrequest_id}/mark-failed`
Auth	Bearer token required

Path Parameters

Parameter	Type	Description
`workspace_name`	string	The unique name of the workspace
`runsession_id`	integer	The ID of the run session
`runrequest_id`	integer	The ID of the run request

Response 200 OK

Returns the updated run request marked as failed.