Get Playbook Run
GET/external/v1/playbook-runs/:idRetrieves one run with every step. Each step is a task: complete it with Complete Task using its task_id, and the run advances.
Authentication
Requires playbooks:read permission.
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Run identifier (UUID) |
Request
bash
curl --request GET \
--url "https://app.getraze.com/external/v1/playbook-runs/3ef8c1c3-c081-4187-a6aa-657fbf1a813b" \
--header "X-API-Key: YOUR_API_KEY"javascript
const axios = require('axios');
const runId = '3ef8c1c3-c081-4187-a6aa-657fbf1a813b';
const response = await axios.get(
`https://app.getraze.com/external/v1/playbook-runs/${runId}`,
{ headers: { 'X-API-Key': 'YOUR_API_KEY' } }
);
console.log(response.data);python
import requests
run_id = '3ef8c1c3-c081-4187-a6aa-657fbf1a813b'
response = requests.get(
f'https://app.getraze.com/external/v1/playbook-runs/{run_id}',
headers={'X-API-Key': 'YOUR_API_KEY'}
)
print(response.json())Response
The fields of List Playbook Runs, plus steps.
json
{
"success": true,
"data": {
"id": "3ef8c1c3-c081-4187-a6aa-657fbf1a813b",
"playbook": { "id": "9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62", "name": "Onboarding" },
"status": "in_progress",
"is_overdue": true,
"progress": { "steps_done": 1, "steps_total": 3, "overdue_steps": 1 },
"steps": [
{
"position": 1,
"task_id": "97f785b0-d1ce-4a2b-8142-89c2fb88d501",
"title": "Welcome call",
"task_type": "call",
"priority": "high",
"status": "completed",
"is_overdue": false,
"due_date": "2026-10-13T14:00:00.000Z",
"completed_at": "2026-10-13T13:40:00.000Z",
"completed_by": { "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva" },
"assignees": [{ "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva" }],
"subtasks": { "done": 0, "total": 0 }
},
{
"position": 2,
"task_id": "a8e9f0b1-c2d3-4e5f-8a9b-0c1d2e3f4a5b",
"title": "Send the onboarding kit",
"task_type": "email",
"priority": "medium",
"status": "pending",
"is_overdue": true,
"due_date": "2026-10-14T14:00:00.000Z",
"completed_at": null,
"completed_by": null,
"assignees": [],
"subtasks": { "done": 1, "total": 3 }
}
]
}
}Step Fields
| Field | Type | Description |
|---|---|---|
position | integer | Order of the step (1-based) |
task_id | string | The task this step created (see Get Task) |
title / task_type / priority | string | Task fields |
status | string | pending, in_progress, completed or cancelled |
is_overdue | boolean | Open and past due_date |
due_date | string | UTC timestamp |
completed_at / completed_by | string / object | Nullable |
assignees | array | Users responsible for the step |
subtasks | object | Checklist progress inside the step |
Errors
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | id is not a UUID |
| 404 | NOT_FOUND | Run not found in this account |