Process Runs

Process runs are active or completed instances of a process template. Each run contains its own copy of the tasks with independent completion status and form field values.

List Runs


GET /api/v1/process-runs

Returns a paginated list of process runs, newest first.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (1-100)
`cursor`	string	—	Cursor for pagination
`template_id`	string	—	Filter by template ID
`status`	string	—	Filter by status: `active` or `completed`

Example Request


# List active runs for a specific template
curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs?status=active&template_id=CcIJXVzRuiP5HvI26FTE"

Example Response


{
  "data": [
    {
      "id": "CWpVWwuj7Jkvl3Smlyxb",
      "template_id": "CcIJXVzRuiP5HvI26FTE",
      "title": "Employee Onboarding - Jane Smith",
      "status": "active",
      "started_by": "user123",
      "team_id": "team_abc",
      "timezone": "Pacific/Auckland",
      "due_date": null,
      "is_shared": false,
      "sections": [
        { "id": "sec_abc", "title": "First Week", "order": 0, "color": "#EC4899" }
      ],
      "created_at": "2026-03-27T02:08:05.224Z",
      "updated_at": null,
      "completed_at": null
    }
  ],
  "pagination": {
    "next_cursor": "CWpVWwuj7Jkvl3Smlyxb",
    "has_more": false
  }
}

Create a Run


POST /api/v1/process-runs

Start a new process run from a template. The template must be published.

Request Body

Field	Type	Required	Description
`template_id`	string	Yes	ID of the template to run
`name`	string	No	Custom title for the run (defaults to template title)
`due_date`	string	No	ISO 8601 due date
`actor_email`	string	No	Email of the person starting the run (defaults to `"api"`)
`custom_elements`	array	No	Pre-fill form field values (see below)

Pre-filling Form Fields

You can set initial values for form fields when creating a run:


{
  "template_id": "CcIJXVzRuiP5HvI26FTE",
  "name": "Onboarding - Jane Smith",
  "custom_elements": [
    {
      "task_id": "Y9Rxzi3uDOvGAYojkHti",
      "element_id": "elem_001",
      "value": "Jane Smith"
    },
    {
      "task_id": "Y9Rxzi3uDOvGAYojkHti",
      "element_id": "elem_002",
      "value": "jane@company.com"
    }
  ]
}

Use the List Template Tasks endpoint to discover task IDs and element IDs for pre-filling.

Example Request


curl -X POST \
  -H "Authorization: Bearer nxs_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "CcIJXVzRuiP5HvI26FTE", "name": "Onboarding - Jane Smith"}' \
  "https://getnextstep.io/api/v1/process-runs"

Example Response (201 Created)


{
  "data": {
    "id": "new_run_id",
    "template_id": "CcIJXVzRuiP5HvI26FTE",
    "title": "Onboarding - Jane Smith",
    "status": "active",
    "started_by": "api",
    "team_id": "team_abc",
    "timezone": "Pacific/Auckland",
    "created_at": "2026-04-07T10:00:00.000Z",
    "completed_at": null
  }
}

Get a Run


GET /api/v1/process-runs/:id

Returns a single process run by ID.

Example Request


curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb"

List Run Tasks


GET /api/v1/process-runs/:id/tasks

Returns all tasks in a process run, ordered by position. Each task includes its current completion status and form field values.

Query Parameters

Parameter	Type	Default	Description
`limit`	integer	20	Number of results (1-100)
`cursor`	string	—	Cursor for pagination

Example Request


curl -H "Authorization: Bearer nxs_live_your_key" \
  "https://getnextstep.io/api/v1/process-runs/CWpVWwuj7Jkvl3Smlyxb/tasks"

Example Response


{
  "data": [
    {
      "id": "POPXQSSPZnYNjUz7QBbn",
      "instance_id": "CWpVWwuj7Jkvl3Smlyxb",
      "template_task_id": "Y9Rxzi3uDOvGAYojkHti",
      "title": "Review employee details",
      "completed": true,
      "completed_at": "2026-04-07T02:29:18.865Z",
      "completed_by": "user123",
      "order": 0,
      "section_id": "sec_abc",
      "assignee": "user123",
      "is_essential": false,
      "type": "task",
      "custom_elements": [
        {
          "id": "elem_001",
          "type": "shortText",
          "label": "Employee Name",
          "value": "Jane Smith",
          "required": true,
          "display_only": false
        },
        {
          "id": "elem_002",
          "type": "email",
          "label": "Employee Email",
          "value": "jane@company.com",
          "required": true,
          "display_only": false
        }
      ],
      "created_at": "2026-03-27T02:08:05.224Z"
    }
  ],
  "pagination": {
    "next_cursor": "POPXQSSPZnYNjUz7QBbn",
    "has_more": true
  }
}