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. A run is a frozen snapshot — it copies the template’s tasks and form fields at creation time, so later template edits never affect existing runs.

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). `title` is accepted as an alias.
`due_date`	string	No	ISO 8601 due date
`actor_email`	string	No	Email of an active team member to attribute the run to (see below)
`custom_elements`	array	No	Pre-fill form field values (see below)

Attributing the run to a person

By default, API-created runs are attributed to "api" and appear only under the Team tab in the app — not in any individual’s Personal tab. To make a run show up in a specific person’s Personal tab, pass their email as actor_email. The email must belong to an active member of the team; if it doesn’t match a member, the run falls back to "api". When attributed, any tasks assigned to the “workflow runner” are also assigned to that person, and they receive assignment notification emails.

Custom elements (form fields) are inherited from the template only at run-creation time. custom_elements can pre-fill the values of fields that already exist on the template, but cannot add new fields. To change which fields a run has, edit the template and republish: unpublish it (POST /process-templates/:id/publish with { "published": false }), make your edits, then publish again. New runs pick up the changes; existing runs are unaffected.

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
  }
}