Skip to content

List Playbook Runs ​

GET /external/v1/playbook-runs

Returns 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 ​

ParameterTypeDefaultDescription
pageinteger1Page number
limitinteger50Items per page (1-100)
playbook_idstring-Only runs of this playbook
statusstring-in_progress, completed or cancelled
overdueboolean-true = only in-progress runs with at least one overdue step
contact_idstring-Only runs of this contact
opportunity_idstring-Only runs of this opportunity
searchstring-Partial match on contact name, company, playbook name or run title
started_after / started_beforestring (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 ​

FieldTypeDescription
idstringRun identifier
playbookobjectPlaybook the run came from. The name is the one it had when the run started
titlestringRun title (internal runs)
statusstringin_progress, completed (every step done) or cancelled
is_overduebooleanIn progress with at least one overdue step
context.typestringcontact, internal or client (a run about a client account, created in the app)
context.namestringWhat the app shows as the run name: client, contact or title
context.contact / context.opportunity / context.conversation_idobject / stringWhat the run is about (nullable)
progressobjectSteps done, total steps and overdue steps
current_stepobjectFirst step not done yet; null when the run is not in progress
started_byobjectWho started the run
started_at / completed_at / cancelled_atstringUTC timestamps (nullable)
cancelled_reasonstringReason given when cancelling (nullable)

GetRaze - AI-Powered Lead Generation