> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Views API

> Save and manage filters and columns for observability pages through the public Views API.

Use `/v3/views` to manage the saved Views used by [Traces](/ai-studio/observability/traces) and [Logs](/ai-studio/observability/logs). A View stores a display name, page, filter string, columns, optional column labels, and visibility.

## Access

Authenticate with a workspace-wide API key and grant the `view` permission domain. Read access permits listing and retrieving shared Views; write access also permits creating, updating, and deleting them. Project-scoped API keys cannot access workspace Views.

Private Views require a user session. Only users listed in `private_for_ids` can list, retrieve, update, or delete a private View. API keys can access shared Views only, and cannot create private Views or convert shared Views to private Views.

## Create and retrieve a View

Set `display_name` and `page`. Supported pages are `traces`, `traces-studio`, `logs`, and `finder`. Duplicate names are allowed.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST "https://my.orq.ai/v3/views" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "display_name": "Customer investigations",
    "page": "traces-studio",
    "columns": ["name", "attributes.customer.id"],
    "column_labels": {"attributes.customer.id": "Customer"}
  }'
```

Create, retrieve, and update responses wrap the saved object in `view`. Use the returned `view.id` with `GET /v3/views/{view_id}`.

Set `is_private: true` when creating a View with a user session to limit access to that user. Set `is_default: true` to make a View the default for its page and visibility: a shared default replaces the previous shared default, while a private default replaces that user's private default on the same page.

## List Views

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://my.orq.ai/v3/views?page=traces-studio&limit=25" \
  -H "Authorization: Bearer $ORQ_API_KEY"
```

The response contains `data` and `has_more`. Set `starting_after` to the last returned View's `id` for the next page, or `ending_before` to the first returned View's `id` for the previous page. Use one cursor at a time. The default `limit` is 10 and the maximum is 100. Omit `page` to list all accessible Views.

## Update and delete a View

Send changed fields to `PATCH /v3/views/{view_id}`. Omitted scalar fields retain their saved values. When setting `update_mask`, include every field to change; fields outside the mask retain their saved values. To clear all columns or column labels, include their paths in the mask. Protobuf JSON encodes the mask as a comma-separated string.

```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH "https://my.orq.ai/v3/views/$VIEW_ID" \
  -H "Authorization: Bearer $ORQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "",
    "columns": [],
    "column_labels": {},
    "update_mask": "description,columns,columnLabels"
  }'
```

Delete a View with `DELETE /v3/views/{view_id}`. A successful deletion returns an empty JSON object. Missing Views, Views in another workspace, and private Views outside the caller's access return `404`.

See the [Views API reference](/reference/views/list-saved-views) for the complete request and response fields. Replace legacy `/v2/views` and `/v2/workspaces/views` calls with `/v3/views` and the response shapes above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.