# Views endpoints

> Shared saved views (filters + sort) and the runs they select. Every operation with parameters, body, responses, errors and examples.

Source: https://developers.processcart.com/reference/views

Shared saved views (filters + sort) and the runs they select.

Base URL `https://app.processcart.com/api/v1`. Every operation below is also in the [OpenAPI document](https://developers.processcart.com/openapi.json) and the [interactive reference](https://developers.processcart.com/reference).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [List shared views](#listViews) | <code class="pc-docs-wrap">GET /v1<wbr>/views</code> | Scope `views:read` |
| [Create a shared view](#createView) | <code class="pc-docs-wrap">POST /v1<wbr>/views</code> | Scope `views:write` |
| [Get a shared view](#getView) | <code class="pc-docs-wrap">GET /v1<wbr>/views<wbr>/{id}</code> | Scope `views:read` |
| [Update a shared view](#updateView) | <code class="pc-docs-wrap">PATCH /v1<wbr>/views<wbr>/{id}</code> | Scope `views:write` |
| [Delete a shared view](#deleteView) | <code class="pc-docs-wrap">DELETE /v1<wbr>/views<wbr>/{id}</code> | Scope `views:write` |
| [List the runs a view selects](#listViewRuns) | <code class="pc-docs-wrap">GET /v1<wbr>/views<wbr>/{id}<wbr>/runs</code> | Scope `runs:read` |

## GET /v1/views
**List shared views.** Scope `views:read` · paginated (`{ data, nextCursor, hasMore }`). Operation id `listViews` · [open in the API reference](https://developers.processcart.com/reference#tag/views/GET/v1/views).

Every saved view shared with the workspace (`org`) or with groups (`groups`), by name, with the board query each one selects. Private views never appear. `updatedSince` turns the list into an incremental sync ordered by `updatedAt` ascending (inclusive).

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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. |
| `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. | [ListViewsResponse](https://developers.processcart.com/reference/schemas#listviewsresponse) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
      "name": "Alpha board",
      "query": {
        "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
        "status": [],
        "priority": [],
        "labels": [],
        "assignee": null,
        "due": null,
        "q": "",
        "qMode": "prefix",
        "sort": {
          "key": "started",
          "dir": "desc"
        },
        "columns": [
          "status",
          "priority",
          "progress",
          "key_date",
          "due",
          "assignees",
          "started"
        ]
      },
      "visibility": "org",
      "groupIds": [],
      "owner": {
        "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
        "name": "Fixture Admin"
      },
      "createdAt": "2026-10-13T00:39:38.376Z",
      "updatedAt": "2026-10-13T00:39:38.376Z"
    },
    {
      "id": "11478b4b-5c42-4bb8-829e-65d4c8493a3a",
      "name": "Reviewers' queue",
      "query": {
        "workflowId": null,
        "status": [
          "active",
          "on_hold"
        ],
        "priority": [],
        "labels": [],
        "assignee": {
          "kind": "group",
          "id": "46139a8e-9621-4f2c-98f3-8975bb8d2589"
        },
        "due": null,
        "q": "",
        "qMode": "prefix",
        "sort": {
          "key": "started",
          "dir": "desc"
        },
        "columns": [
          "status",
          "priority",
          "progress",
          "key_date",
          "due",
          "assignees",
          "started"
        ]
      },
      "visibility": "groups",
      "groupIds": [
        "46139a8e-9621-4f2c-98f3-8975bb8d2589"
      ],
      "owner": {
        "userId": "4f9b94a3-9d38-479d-a0f3-9c8f01dcff92",
        "name": "Fixture Member"
      },
      "createdAt": "2026-10-13T00:39:38.462Z",
      "updatedAt": "2026-10-13T00:39:38.462Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```


## POST /v1/views
**Create a shared view.** Scope `views:write` · accepts `Idempotency-Key`. Operation id `createView` · [open in the API reference](https://developers.processcart.com/reference#tag/views/POST/v1/views).

Saves a board query as a view shared with everyone (default) or with specific groups. Send only the query members you set — the rest take the board's defaults, and the response carries the complete query. The view is owned by the member who created the API key, who must still be a Builder or Admin of the workspace (else 403 — mint a key as a current Admin). Each owner keeps at most 30 views.

**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`, [CreateViewBody](https://developers.processcart.com/reference/schemas#createviewbody)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `query` | object | yes | The board query the view selects. Send only the members you set; the rest take the board's defaults: `{"workflowId":null,"status":["active","on_hold"],"priority":[],"labels":[],"assignee":null,"due":null,"q":"","qMode":"prefix","sort":{"key":"started","dir":"desc"},"columns":["status","priority","progress","key_date","due","assignees","started"]}`. `sort.key` without `dir` takes that key's natural direction (`asc` for `name`, `key_date` and `due`, else `desc`). An unknown member is a 422. |
| `visibility` | `"org"` \\| `"groups"` | no |  |
| `groupIds` | [Uuid](https://developers.processcart.com/reference/schemas#uuid)[] | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 201 | Created. `Location` names the new resource. | [View](https://developers.processcart.com/reference/schemas#view) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "Active by name",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [
      "active"
    ],
    "sort": {
      "key": "name"
    }
  }
}
```

**Example response** (201)

```json
{
  "id": "6885f52f-03a9-464e-b9bb-95b359a3a57b",
  "name": "Active by name",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [
      "active"
    ],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "name",
      "dir": "asc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "org",
  "groupIds": [],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:39.520Z",
  "updatedAt": "2026-10-13T00:39:39.520Z"
}
```


## GET /v1/views/{id}
**Get a shared view.** Scope `views:read`. Operation id `getView` · [open in the API reference](https://developers.processcart.com/reference#tag/views/GET/v1/views/{id}).

One shared view with its query. A private view — even one owned by the member who created the key — is a 404.

**Path parameters**

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

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [View](https://developers.processcart.com/reference/schemas#view) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
  "name": "Alpha board",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "started",
      "dir": "desc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "org",
  "groupIds": [],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:38.376Z",
  "updatedAt": "2026-10-13T00:39:38.376Z"
}
```


## PATCH /v1/views/{id}
**Update a shared view.** Scope `views:write` · accepts `Idempotency-Key`. Operation id `updateView` · [open in the API reference](https://developers.processcart.com/reference#tag/views/PATCH/v1/views/{id}).

Renames a view, changes its query or changes who it is shared with. A `query` changes only the members it sends; the rest keep the view's stored values. Only a view owned by the member who created the key can be changed through the API, and that member must still be a Builder or Admin of the workspace (403 `not_allowed_for_key` otherwise). Switching to `org` drops the group list; `groups` needs at least one group of the workspace.

**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. |

**Request body** — `application/json`, [UpdateViewBody](https://developers.processcart.com/reference/schemas#updateviewbody)

| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | no |  |
| `query` | object | no | Changes to the view's board query. Send only the members you change; the rest keep the view's stored values (`null` clears `workflowId`, `assignee` or `due`). `sort.key` without `dir` takes that key's natural direction. An unknown member is a 422. |
| `visibility` | `"org"` \\| `"groups"` | no |  |
| `groupIds` | [Uuid](https://developers.processcart.com/reference/schemas#uuid)[] | no |  |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [View](https://developers.processcart.com/reference/schemas#view) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `not_allowed_for_key` — Not allowed for this key; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 413 | `payload_too_large` — Payload too large. | [Problem](https://developers.processcart.com/errors) |
| 415 | `unsupported_media_type` — Unsupported media type. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`not_allowed_for_key`](https://developers.processcart.com/errors#not_allowed_for_key) — Not allowed for this key
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 413 [`payload_too_large`](https://developers.processcart.com/errors#payload_too_large) — Payload too large
- 415 [`unsupported_media_type`](https://developers.processcart.com/errors#unsupported_media_type) — Unsupported media type
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example request**

```json
{
  "name": "Alpha board (renamed)"
}
```

**Example response** (200)

```json
{
  "id": "d9d20dae-2010-4211-8b78-d724b96d3125",
  "name": "Alpha board (renamed)",
  "query": {
    "workflowId": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
    "status": [],
    "priority": [],
    "labels": [],
    "assignee": null,
    "due": null,
    "q": "",
    "qMode": "prefix",
    "sort": {
      "key": "started",
      "dir": "desc"
    },
    "columns": [
      "status",
      "priority",
      "progress",
      "key_date",
      "due",
      "assignees",
      "started"
    ]
  },
  "visibility": "groups",
  "groupIds": [
    "46139a8e-9621-4f2c-98f3-8975bb8d2589"
  ],
  "owner": {
    "userId": "fde8fad1-9f03-4acb-bafe-91b9a9583a60",
    "name": "Fixture Admin"
  },
  "createdAt": "2026-10-13T00:39:38.376Z",
  "updatedAt": "2026-10-13T00:39:41.545Z"
}
```


## DELETE /v1/views/{id}
**Delete a shared view.** Scope `views:write` · accepts `Idempotency-Key`. Operation id `deleteView` · [open in the API reference](https://developers.processcart.com/reference#tag/views/DELETE/v1/views/{id}).

Removes any shared view of the workspace, whoever owns it (the same power an Admin has in the app); the deletion is recorded in the audit log under the key's name. A private view is a 404.

**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. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 204 | Done; no body. | — |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope; `read_only_key` — Read-only key. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 409 | `idempotency_in_progress` — Request in progress. | [Problem](https://developers.processcart.com/errors) |
| 422 | `idempotency_key_reused` — Idempotency key reused; `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 403 [`read_only_key`](https://developers.processcart.com/errors#read_only_key) — Read-only key
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 409 [`idempotency_in_progress`](https://developers.processcart.com/errors#idempotency_in_progress) — Request in progress
- 422 [`idempotency_key_reused`](https://developers.processcart.com/errors#idempotency_key_reused) — Idempotency key reused
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable


## GET /v1/views/{id}/runs
**List the runs a view selects.** Scope `runs:read` · the key's allowlist narrows the rows (never a 403 — rows outside it are absent) · paginated (`{ data, nextCursor, hasMore }`). Operation id `listViewRuns` · [open in the API reference](https://developers.processcart.com/reference#tag/views/GET/v1/views/{id}/runs).

Applies the view's stored query — filters and sort, exactly as the board does — and returns FULL Run resources, paged like `GET /v1/runs` and limited to the key's allowlist. A view that filters by the viewer (`assignee: me`) cannot be resolved for a key: call `GET /v1/runs?assignee=u:<user id>` instead (422). A view sorted by progress is a 422 too (that sort is computed in the app). `updatedSince` orders by `updatedAt` ascending instead of the view's sort.

**Path parameters**

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

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

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `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. |
| `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. | [ListViewRunsResponse](https://developers.processcart.com/reference/schemas#listviewrunsresponse) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 404 | `not_found` — Not found. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 404 [`not_found`](https://developers.processcart.com/errors#not_found) — Not found
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "c4f32706-55c2-4524-8193-8ca38969a675",
      "name": "View run one",
      "status": "active",
      "priority": "none",
      "labels": [],
      "labelDetails": [],
      "dueAt": null,
      "keyDate": null,
      "revision": 1,
      "updatedAt": "2026-10-13T00:39:49.561Z",
      "startedAt": "2026-10-13T00:39:49.462Z",
      "startedBy": "api",
      "startedByUserId": null,
      "schedule": null,
      "scheduledFor": null,
      "completedAt": null,
      "deletedAt": null,
      "workflow": {
        "id": "165fe8d7-471f-4748-b8ab-a6ee3478cd7d",
        "name": "Order fulfillment"
      },
      "versionId": "36e87c9b-845a-4294-942e-809c38fa6137",
      "url": "https://app.processcart.com/runs/c4f32706-55c2-4524-8193-8ca38969a675",
      "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": "fde8fad1-9f03-4acb-bafe-91b9a9583a60"
            }
          ],
          "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": "Ann",
          "formatted": "Ann",
          "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": 1700,
          "formatted": "$1,700.00",
          "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": 3400,
          "formatted": "$3,400.00",
          "visible": true
        },
        {
          "key": "source",
          "label": "Source",
          "type": "hidden",
          "format": null,
          "taskKey": "details",
          "value": null,
          "formatted": "",
          "visible": false
        }
      ]
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```