Runs endpoints

Runs of a workflow — the central resource: every field value (canonical + formatted) and every task's state in one document. Every operation with parameters, body, responses, errors and examples.

View this page as Markdown

Runs of a workflow — the central resource: every field value (canonical + formatted) and every task's state in one document.

Base URL https://app.processcart.com/api/v1. Every operation below is also in the OpenAPI document and the interactive reference.

Operation	Method and path	Scope
List runs	`GET /v1/runs`	Scope `runs:read`
Start a run	`POST /v1/runs`	Scope `runs:write`
Get a run	`GET /v1/runs/{id}`	Scope `runs:read`
Update a run's name, priority, labels, due date or status	`PATCH /v1/runs/{id}`	Scope `runs:write`
Move a run to Trash	`DELETE /v1/runs/{id}`	Scope `runs:write`
Restore a run from Trash	`POST /v1/runs/{id}/restore`	Scope `runs:write`

GET /v1/runs

List runs. Scope runs:read · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated ({ data, nextCursor, hasMore }). Operation id listRuns · open in the API reference.

Lists the runs the key may see as FULL Run resources (fields and tasks included), newest first. Filter by workflow, status, priority, labels, assignee (u:<id> / g:<id>), due window or run name; updatedSince turns the list into an incremental sync ordered by updatedAt ascending (inclusive — overlap by a minute and dedupe by (id, revision)). Trashed runs are hidden unless includeTrashed=true. limit is capped at 100.

Query parameters (an unknown parameter is a 422 validation_failed with errors[].code = "unknown_parameter")

Name	Type	Required	Description
`workflowId`	string (uuid)	no
`status`	`"active"` \	`"completed"` \	`"on_hold"` \
`priority`	`"none"` \	`"low"` \	`"medium"` \
`labels`	string[]	no	Comma-separated (or repeat the parameter).
`assignee`	string	no
`due`	`"overdue"` \	`"today"` \	`"week"` \
`q`	string	no
`qMode`	`"prefix"` \	`"contains"`	no
`updatedSince`	string (date-time)	no	Incremental sync: only items whose `updatedAt` is at or after this instant (inclusive), ordered by `updatedAt` ascending; an explicit conflicting `sort` / `order` is a 422. Overlap by a minute and dedupe: a Run by `(id, revision)`, any other item (workflow, view, webhook, schedule, automation rule) by `(id, updatedAt)` — a higher `revision` or a later `updatedAt` replaces the copy you hold, an equal one is unchanged.
`includeTrashed`	boolean	no
`sort`	`"startedAt"` \	`"updatedAt"` \	`"name"` \
`order`	`"asc"` \	`"desc"`	no
`limit`	integer	no
`cursor`	string	no	The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422.

Responses

Status	Meaning	Body
200	OK.	RunList
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
422	`validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
405 method_not_allowed — Method not allowed
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "data": [
    {
      "id": "8b84a82b-e9d8-4657-aa7c-50452cf48c8d",
      "name": "Order 1001",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 1,
      "updatedAt": "2026-10-13T01:10:36.904Z",
      "startedAt": "2026-10-13T01:10:36.815Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
        "name": "Order fulfillment"
      },
      "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
      "url": "https://app.processcart.com/runs/8b84a82b-e9d8-4657-aa7c-50452cf48c8d",
      "tasks": [
        {
          "key": "details",
          "title": "Details",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "review",
          "title": "Review",
          "kind": "approval",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [
            {
              "kind": "user",
              "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
            }
          ],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "stop",
          "title": "Sign-off",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "wrapup",
          "title": "Wrap up",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": true,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        }
      ],
      "fields": [
        {
          "key": "customer",
          "label": "Customer",
          "type": "text",
          "format": "none",
          "taskKey": "details",
          "value": "Grace Hopper",
          "formatted": "Grace Hopper",
          "visible": true
        },
        {
          "key": "order_code",
          "label": "Order code",
          "type": "text",
          "format": "custom",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "memo",
          "label": "Memo",
          "type": "textarea",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "quantity",
          "label": "Quantity",
          "type": "number",
          "format": "number",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "amount",
          "label": "Amount",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "fee",
          "label": "Fee",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate",
          "label": "Rate",
          "type": "number",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate_text",
          "label": "Rate (text)",
          "type": "text",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "ship_date",
          "label": "Ship date",
          "type": "date",
          "format": "date",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "start_time",
          "label": "Start time",
          "type": "time",
          "format": "time",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "gift_wrap",
          "label": "Gift wrap",
          "type": "dropdown",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "Yes",
            "No"
          ]
        },
        {
          "key": "tags",
          "label": "Tags",
          "type": "multi_choice",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "A",
            "B",
            "C"
          ]
        },
        {
          "key": "agree",
          "label": "Agree",
          "type": "checkbox",
          "format": null,
          "taskKey": "details",
          "value": false,
          "formatted": "No",
          "visible": true
        },
        {
          "key": "contact_email",
          "label": "Contact email",
          "type": "email",
          "format": "email",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "website",
          "label": "Website",
          "type": "url",
          "format": "url",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "phone",
          "label": "Phone",
          "type": "phone",
          "format": "phone",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "owner",
          "label": "Owner",
          "type": "members",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "steps",
          "label": "Steps",
          "type": "subtasks",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "items": [
            {
              "key": "photos",
              "label": "Photos"
            },
            {
              "key": "invoice",
              "label": "Invoice"
            }
          ]
        },
        {
          "key": "contract",
          "label": "Contract",
          "type": "file",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "double_amount",
          "label": "Double amount",
          "type": "formula",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    },
    {
      "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
      "name": "Order 1002",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 7,
      "updatedAt": "2026-10-13T01:10:35.496Z",
      "startedAt": "2026-10-13T01:10:02.387Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
        "name": "Order fulfillment"
      },
      "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
      "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
      "tasks": [
        {
          "key": "details",
          "title": "Details",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "review",
          "title": "Review",
          "kind": "approval",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [
            {
              "kind": "user",
              "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
            }
          ],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "stop",
          "title": "Sign-off",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": false,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        },
        {
          "key": "wrapup",
          "title": "Wrap up",
          "kind": "standard",
          "section": "Intake",
          "state": "todo",
          "visible": true,
          "locked": true,
          "dueAt": null,
          "assignees": [],
          "completedAt": null,
          "completedByUserId": null
        }
      ],
      "fields": [
        {
          "key": "customer",
          "label": "Customer",
          "type": "text",
          "format": "none",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "order_code",
          "label": "Order code",
          "type": "text",
          "format": "custom",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "memo",
          "label": "Memo",
          "type": "textarea",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "quantity",
          "label": "Quantity",
          "type": "number",
          "format": "number",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "amount",
          "label": "Amount",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "fee",
          "label": "Fee",
          "type": "number",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate",
          "label": "Rate",
          "type": "number",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "rate_text",
          "label": "Rate (text)",
          "type": "text",
          "format": "percent",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "ship_date",
          "label": "Ship date",
          "type": "date",
          "format": "date",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "start_time",
          "label": "Start time",
          "type": "time",
          "format": "time",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "gift_wrap",
          "label": "Gift wrap",
          "type": "dropdown",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "Yes",
            "No"
          ]
        },
        {
          "key": "tags",
          "label": "Tags",
          "type": "multi_choice",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "choices": [
            "A",
            "B",
            "C"
          ]
        },
        {
          "key": "agree",
          "label": "Agree",
          "type": "checkbox",
          "format": null,
          "taskKey": "details",
          "value": false,
          "formatted": "No",
          "visible": true
        },
        {
          "key": "contact_email",
          "label": "Contact email",
          "type": "email",
          "format": "email",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "website",
          "label": "Website",
          "type": "url",
          "format": "url",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "phone",
          "label": "Phone",
          "type": "phone",
          "format": "phone",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "owner",
          "label": "Owner",
          "type": "members",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "steps",
          "label": "Steps",
          "type": "subtasks",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true,
          "items": [
            {
              "key": "photos",
              "label": "Photos"
            },
            {
              "key": "invoice",
              "label": "Invoice"
            }
          ]
        },
        {
          "key": "contract",
          "label": "Contract",
          "type": "file",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "double_amount",
          "label": "Double amount",
          "type": "formula",
          "format": "currency",
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    }
  ],
  "nextCursor": "eyJ2IjoiMjAyNi0xMC0xM1QwMToxMDowMi4zODcwMDBaIiwiaWQiOiI4NDVkNDc0NS00Y2MxLTQ2ZmUtOWQ2Yy0zY2ZlYWQ3NDU0NGYiLCJoIjoiYjU0MzliODk0MmUxZDhlNiJ9",
  "hasMore": true
}

POST /v1/runs

Start a run. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key. Operation id startRun · open in the API reference.

Starts a run of a workflow's published version with a name, optional field values (any writable field; kickoff fields marked required must be present), priority, labels and due date — in one transaction. A visible kickoff field (required or not) whose value breaks its bounds or rules is refused with 422 validation_failed (errors[].code invalid_value), the same gate as the app's Start dialog; other fields are accepted and flagged in validationError, as on PATCH /runs/{id}/fields. Returns the new Run (revision: 1) and an absolute Location header.

Request headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored.

Request body — application/json, RunStart

Property	Type	Required	Description
`workflowId`	Uuid	yes
`name`	string	yes
`fields`	FieldsWrite	no
`priority`	RunPriority	no
`labels`	string[]	no
`dueAt`	Instant \	CalendarDate \	null

Responses

Status	Meaning	Body
201	Created. `Location` names the new resource.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `workflow_not_published` — Workflow not published.	Problem
413	`payload_too_large` — Payload too large.	Problem
415	`unsupported_media_type` — Unsupported media type.	Problem
422	`field_not_writable` — Field is not writable; `idempotency_key_reused` — Idempotency key reused; `required_fields_unsatisfied` — Required fields unsatisfied; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 workflow_not_published — Workflow not published
413 payload_too_large — Payload too large
415 unsupported_media_type — Unsupported media type
422 field_not_writable — Field is not writable
422 idempotency_key_reused — Idempotency key reused
422 required_fields_unsatisfied — Required fields unsatisfied
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example request

{
  "workflowId": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
  "name": "ORD 2026-10-15 Acme Corp",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "dueAt": "2026-10-20",
  "fields": {
    "customer": "Ada Lovelace",
    "amount": "$1,700.00",
    "rate": "5%",
    "rate_text": 0.05,
    "quantity": 1250,
    "fee": 900,
    "ship_date": "2026-10-15",
    "start_time": "14:30",
    "gift_wrap": "Yes",
    "tags": [
      "A",
      "C"
    ],
    "agree": true,
    "contact_email": "Ada@Example.com",
    "website": "example.com",
    "phone": "(415) 555-0100",
    "owner": [
      "e9e90546-8500-4502-a8a3-0f705c013cfd"
    ],
    "steps": [
      "photos"
    ],
    "source": "zapier",
    "order_code": "AB-1234",
    "memo": "Two lines\nhere"
  }
}

Example response (201)

{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "status": "active",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "labelDetails": [
    {
      "id": "rush",
      "name": "Rush",
      "color": "#dc2626"
    }
  ],
  "dueAt": "2026-10-21T06:59:59.000Z",
  "keyDate": "2026-10-15",
  "revision": 1,
  "updatedAt": "2026-10-13T01:09:29.022Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}

GET /v1/runs/{id}

Get a run. Scope runs:read · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it). Operation id getRun · open in the API reference.

Returns one run with every field value (canonical + formatted) and task state, plus its revision — send it back as Expected-Revision on a write that must not overwrite a newer change. A run in Trash loads with deletedAt set.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
422	`validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
404 not_found — Not found
405 method_not_allowed — Method not allowed
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp",
  "status": "active",
  "priority": "urgent",
  "labels": [
    "rush"
  ],
  "labelDetails": [
    {
      "id": "rush",
      "name": "Rush",
      "color": "#dc2626"
    }
  ],
  "dueAt": "2026-10-21T06:59:59.000Z",
  "keyDate": "2026-10-15",
  "revision": 1,
  "updatedAt": "2026-10-13T01:09:29.022Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}

PATCH /v1/runs/{id}

Update a run's name, priority, labels, due date or status. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key · accepts Expected-Revision (409 revision_mismatch when stale). Operation id updateRun · open in the API reference.

Changes run-level attributes under the run lock. status is applied first; an archived run refuses every other change. Label ids are checked against the org's label set. Send Expected-Revision to refuse the write when the run changed since you read it.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes

Request headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored.
`Expected-Revision`	string	no	Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412.

Request body — application/json, RunPatch

Property	Type	Required	Description
`name`	string	no
`priority`	RunPriority	no
`labels`	string[]	no
`dueAt`	Instant \	CalendarDate \	null
`status`	RunStatus	no

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `run_archived` — Run is archived; `run_trashed` — Run is in Trash.	Problem
413	`payload_too_large` — Payload too large.	Problem
415	`unsupported_media_type` — Unsupported media type.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 run_archived — Run is archived
409 run_trashed — Run is in Trash
413 payload_too_large — Payload too large
415 unsupported_media_type — Unsupported media type
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example request

{
  "name": "ORD 2026-10-15 Acme Corp (renamed)",
  "priority": "high",
  "labels": [
    "waiting"
  ],
  "dueAt": "2026-11-01T17:00:00Z"
}

Example response (200)

{
  "id": "33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "name": "ORD 2026-10-15 Acme Corp (renamed)",
  "status": "active",
  "priority": "high",
  "labels": [
    "waiting"
  ],
  "labelDetails": [
    {
      "id": "waiting",
      "name": "Waiting",
      "color": "#f59e0b"
    }
  ],
  "dueAt": "2026-11-01T17:00:00.000Z",
  "keyDate": "2026-10-15",
  "revision": 2,
  "updatedAt": "2026-10-13T01:09:37.189Z",
  "startedAt": "2026-10-13T01:09:28.930Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/33ec8c8c-e219-422c-8dda-5c8633d2e368",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": "Ada Lovelace",
      "formatted": "Ada Lovelace",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": "AB-1234",
      "formatted": "AB-1234",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": "Two lines\nhere",
      "formatted": "Two lines\nhere",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": 1250,
      "formatted": "1,250",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 1700,
      "formatted": "$1,700.00",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": 900,
      "formatted": "$900.00",
      "visible": true,
      "validationError": "Must not exceed $500.00."
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": 0.05,
      "formatted": "5%",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": "2026-10-15",
      "formatted": "Oct 15, 2026",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": "14:30",
      "formatted": "2:30 PM",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": "Yes",
      "formatted": "Yes",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": [
        "A",
        "C"
      ],
      "formatted": "A, C",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": true,
      "formatted": "Yes",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": "ada@example.com",
      "formatted": "ada@example.com",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": "https://example.com/",
      "formatted": "https://example.com/",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": "+14155550100",
      "formatted": "(415) 555-0100",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": [
        "e9e90546-8500-4502-a8a3-0f705c013cfd"
      ],
      "formatted": "Fixture Admin",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": [
        "photos"
      ],
      "formatted": "1 of 2: Photos",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": 3400,
      "formatted": "$3,400.00",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": "zapier",
      "formatted": "zapier",
      "visible": false
    }
  ]
}

DELETE /v1/runs/{id}

Move a run to Trash. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key · accepts Expected-Revision (409 revision_mismatch when stale). Operation id trashRun · open in the API reference.

Soft-deletes the run (recoverable from Trash for 30 days). Returns the Run with deletedAt set; a run already in Trash answers 200 unchanged.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes

Request headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored.
`Expected-Revision`	string	no	Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412.

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "name": "Order 1002",
  "status": "active",
  "priority": "none",
  "labels": [],
  "labelDetails": [],
  "dueAt": null,
  "keyDate": null,
  "revision": 4,
  "updatedAt": "2026-10-13T01:10:28.661Z",
  "startedAt": "2026-10-13T01:10:02.387Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": "2026-10-13T01:10:28.586Z",
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": false
    }
  ]
}

POST /v1/runs/{id}/restore

Restore a run from Trash. Scope runs:write · checked against the key's workflow / folder allowlist (403 not_allowed_for_key outside it) · accepts Idempotency-Key · accepts Expected-Revision (409 revision_mismatch when stale). Operation id restoreRun · open in the API reference.

Brings a trashed run back. A run that is not in Trash answers 200 unchanged; a run whose workflow is itself in Trash is refused (restore the workflow first). Expected-Revision is honored as a compare-and-set.

Path parameters

Name	Type	Required	Description
`id`	string (uuid)	yes

Request headers

Name	Type	Required	Description
`Idempotency-Key`	string	no	Makes the request safe to retry: a second request with the same key and a byte-identical body (and the same `Expected-Revision`) replays the stored response (`Idempotent-Replayed: true`); a different body with the same key is refused (422 `idempotency_key_reused`) and no second resource is created. Keys are stored per workspace for 24 hours and replayed only to the API key that made the request (or the key one rotation away from it); another API key sending the same value is refused (422 `idempotency_key_reused`), so prefix keys per integration. 409, 429 and 5xx answers are never stored.
`Expected-Revision`	string	no	Optimistic concurrency: the run's `revision` you last saw (from any Run body) — a bare integer (`7`) or the same in double quotes (`"7"`); `*` or no header = no precondition. Checked INSIDE the run lock — a stale value is refused with 409 `revision_mismatch` whose body names `currentRevision`. A list or any other value is a 422. A successful write answers its new `revision` in the body. The API sends no `ETag` and refuses `If-Match` (422): CDN layers evaluate `If-Match` against the response and turn a successful write into a 412.

Responses

Status	Meaning	Body
200	OK.	Run
401	No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked.	Problem
403	`insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key.	Problem
404	`not_found` — Not found.	Problem
405	The verb is not supported on this path. `method_not_allowed` — Method not allowed.	Problem
409	`idempotency_in_progress` — Request in progress; `revision_mismatch` — Revision mismatch; `workflow_trashed` — Workflow is in Trash.	Problem
422	`idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed.	Problem
429	`rate_limited` — Too many requests.	Problem
500	`internal_error` — Internal error.	Problem
503	`unavailable` — Service unavailable.	Problem

Errors (every code this operation can answer; see Errors)

401 invalid_api_key — Invalid API key
401 key_revoked — API key revoked
401 unauthorized — Authentication required
403 insufficient_scope — Insufficient scope
403 not_allowed_for_key — Not allowed for this key
403 read_only_key — Read-only key
404 not_found — Not found
405 method_not_allowed — Method not allowed
409 idempotency_in_progress — Request in progress
409 revision_mismatch — Revision mismatch
409 workflow_trashed — Workflow is in Trash
422 idempotency_key_reused — Idempotency key reused
422 validation_failed — Validation failed
429 rate_limited — Too many requests
500 internal_error — Internal error
503 unavailable — Service unavailable

Example response (200)

{
  "id": "845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "name": "Order 1002",
  "status": "active",
  "priority": "none",
  "labels": [],
  "labelDetails": [],
  "dueAt": null,
  "keyDate": null,
  "revision": 5,
  "updatedAt": "2026-10-13T01:10:33.053Z",
  "startedAt": "2026-10-13T01:10:02.387Z",
  "startedBy": "api",
  "startedByUserId": null,
  "schedule": null,
  "scheduledFor": null,
  "completedAt": null,
  "deletedAt": null,
  "workflow": {
    "id": "e1d9bfda-9e93-4cce-8518-b4a185a6d4cb",
    "name": "Order fulfillment"
  },
  "versionId": "6b9a8079-3136-4818-8405-26c69bbac982",
  "url": "https://app.processcart.com/runs/845d4745-4cc1-46fe-9d6c-3cfead74544f",
  "tasks": [
    {
      "key": "details",
      "title": "Details",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "review",
      "title": "Review",
      "kind": "approval",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [
        {
          "kind": "user",
          "userId": "e9e90546-8500-4502-a8a3-0f705c013cfd"
        }
      ],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "stop",
      "title": "Sign-off",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": false,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    },
    {
      "key": "wrapup",
      "title": "Wrap up",
      "kind": "standard",
      "section": "Intake",
      "state": "todo",
      "visible": true,
      "locked": true,
      "dueAt": null,
      "assignees": [],
      "completedAt": null,
      "completedByUserId": null
    }
  ],
  "fields": [
    {
      "key": "customer",
      "label": "Customer",
      "type": "text",
      "format": "none",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "order_code",
      "label": "Order code",
      "type": "text",
      "format": "custom",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "memo",
      "label": "Memo",
      "type": "textarea",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "quantity",
      "label": "Quantity",
      "type": "number",
      "format": "number",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "amount",
      "label": "Amount",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "fee",
      "label": "Fee",
      "type": "number",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate",
      "label": "Rate",
      "type": "number",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "rate_text",
      "label": "Rate (text)",
      "type": "text",
      "format": "percent",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "ship_date",
      "label": "Ship date",
      "type": "date",
      "format": "date",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "start_time",
      "label": "Start time",
      "type": "time",
      "format": "time",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "gift_wrap",
      "label": "Gift wrap",
      "type": "dropdown",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "Yes",
        "No"
      ]
    },
    {
      "key": "tags",
      "label": "Tags",
      "type": "multi_choice",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "choices": [
        "A",
        "B",
        "C"
      ]
    },
    {
      "key": "agree",
      "label": "Agree",
      "type": "checkbox",
      "format": null,
      "taskKey": "details",
      "value": false,
      "formatted": "No",
      "visible": true
    },
    {
      "key": "contact_email",
      "label": "Contact email",
      "type": "email",
      "format": "email",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "website",
      "label": "Website",
      "type": "url",
      "format": "url",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "phone",
      "label": "Phone",
      "type": "phone",
      "format": "phone",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "owner",
      "label": "Owner",
      "type": "members",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "steps",
      "label": "Steps",
      "type": "subtasks",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true,
      "items": [
        {
          "key": "photos",
          "label": "Photos"
        },
        {
          "key": "invoice",
          "label": "Invoice"
        }
      ]
    },
    {
      "key": "contract",
      "label": "Contract",
      "type": "file",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "double_amount",
      "label": "Double amount",
      "type": "formula",
      "format": "currency",
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": true
    },
    {
      "key": "source",
      "label": "Source",
      "type": "hidden",
      "format": null,
      "taskKey": "details",
      "value": null,
      "formatted": "",
      "visible": false
    }
  ]
}