List Playbook Runs
GET/external/v1/playbook-runsReturns the runs of playbooks, newest first. A run is a playbook applied to a contact, an opportunity or an internal title; its steps are tasks. Use this endpoint to follow progress and spot runs that are behind schedule.
Authentication
Requires playbooks:read permission. Every run of the account is listed, whoever started it (as in the app).
Query Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
page | integer | 1 | Page number |
limit | integer | 50 | Items per page (1-100) |
playbook_id | string | - | Only runs of this playbook |
status | string | - | in_progress, completed or cancelled |
overdue | boolean | - | true = only in-progress runs with at least one overdue step |
contact_id | string | - | Only runs of this contact |
opportunity_id | string | - | Only runs of this opportunity |
search | string | - | Partial match on contact name, company, playbook name or run title |
started_after / started_before | string (ISO 8601) | - | Start date range |
Request
bash
curl --request GET \
--url "https://app.getraze.com/external/v1/playbook-runs?status=in_progress&overdue=true" \
--header "X-API-Key: YOUR_API_KEY"javascript
const axios = require('axios');
const response = await axios.get('https://app.getraze.com/external/v1/playbook-runs', {
headers: { 'X-API-Key': 'YOUR_API_KEY' },
params: { status: 'in_progress', overdue: true }
});
console.log(response.data);python
import requests
response = requests.get(
'https://app.getraze.com/external/v1/playbook-runs',
headers={'X-API-Key': 'YOUR_API_KEY'},
params={'status': 'in_progress', 'overdue': 'true'}
)
print(response.json())Response
json
{
"success": true,
"data": [
{
"id": "3ef8c1c3-c081-4187-a6aa-657fbf1a813b",
"playbook": { "id": "9d2c7a1e-4b3f-4e8a-a6d5-1c0b9f8e7d62", "name": "Onboarding" },
"title": null,
"status": "in_progress",
"is_overdue": true,
"context": {
"type": "contact",
"name": "John Doe",
"contact": { "id": "c2f9d1a4-5b7e-4c1a-9e0f-3a8b6d2c4e71", "name": "John Doe", "company": "Acme Inc" },
"opportunity": null,
"conversation_id": null
},
"progress": { "steps_done": 2, "steps_total": 5, "overdue_steps": 1 },
"current_step": {
"task_id": "a8e9f0b1-c2d3-4e5f-8a9b-0c1d2e3f4a5b",
"position": 3,
"title": "Kick-off meeting",
"due_date": "2026-10-17T13:00:00.000Z"
},
"started_by": { "id": "2d19889d-6ff9-4782-8165-32e56bb593c0", "name": "Maria Silva" },
"started_at": "2026-10-13T12:00:00.000Z",
"completed_at": null,
"cancelled_at": null,
"cancelled_reason": null
}
],
"pagination": {
"page": 1,
"per_page": 50,
"total": 2,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}Response Fields
| Field | Type | Description |
|---|---|---|
id | string | Run identifier |
playbook | object | Playbook the run came from. The name is the one it had when the run started |
title | string | Run title (internal runs) |
status | string | in_progress, completed (every step done) or cancelled |
is_overdue | boolean | In progress with at least one overdue step |
context.type | string | contact, internal or client (a run about a client account, created in the app) |
context.name | string | What the app shows as the run name: client, contact or title |
context.contact / context.opportunity / context.conversation_id | object / string | What the run is about (nullable) |
progress | object | Steps done, total steps and overdue steps |
current_step | object | First step not done yet; null when the run is not in progress |
started_by | object | Who started the run |
started_at / completed_at / cancelled_at | string | UTC timestamps (nullable) |
cancelled_reason | string | Reason given when cancelling (nullable) |