> For the complete documentation index, see [llms.txt](https://v2.dataos.info/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/perspectives.md).

# Perspectives

Technical contract for managing saved, reusable query results.

A perspective is a named, reusable view over a successful query result. It lets consumers share or repeatedly retrieve a result by a readable slug instead of submitting the original query again.

## Typical Workflow

1. Submit a query and wait for statement status `SUCCESS`.
2. Create a perspective using that `statement_id`.
3. Share or retrieve it through its slug.
4. When `auto_refresh` is enabled, Vulcan refreshes stale data in the background.

**Visibility rules:**

* A public perspective is visible to all authorized Data Product users.
* A private perspective is visible to its owner and users listed in `allowed_user_ids`.
* Only the owner can update or delete a perspective.

***

## Create a perspective

**API endpoint:** POST /api/v1/perspectives

**Description:** Save a successful statement result as a named perspective. `statement_id` must be a `SUCCESS` statement. If the slug is taken, the API returns `409` with alternative slug suggestions.

| Field              | Type      | Required | Default             | Description                                      |
| ------------------ | --------- | -------- | ------------------- | ------------------------------------------------ |
| `name`             | string    | Yes      | None                | Display name.                                    |
| `statement_id`     | string    | Yes      | None                | Source statement; it must be in `SUCCESS`.       |
| `slug`             | string    | No       | generated from name | URL-safe identifier.                             |
| `description`      | string    | No       | None                | Catalog description.                             |
| `tags`             | string\[] | No       | `[]`                | Searchable tags.                                 |
| `terms`            | string\[] | No       | `[]`                | Associated business terms.                       |
| `auto_refresh`     | boolean   | No       | `true`              | Refresh when upstream data becomes stale.        |
| `is_public`        | boolean   | No       | `false`             | Allow all authorized product users to access it. |
| `allowed_user_ids` | string\[] | No       | `[]`                | Users allowed to access a private perspective.   |

**Request body:**

```json
{
  "name": "<perspective_name>",
  "statement_id": "{{statement_id}}",
  "slug": "<url-friendly-slug>",
  "auto_refresh": true,
  "is_public": false
}
```

**cURL:**

```bash
curl -s -X POST https://$BASE_URL/api/v1/perspectives \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Monthly revenue by store region",
    "statement_id": "stmt_abc123",
    "slug": "monthly-revenue-by-store-region",
    "description": "Governed monthly revenue view",
    "tags": ["sales", "monthly"],
    "auto_refresh": true,
    "is_public": false,
    "allowed_user_ids": ["sales-analyst"]
  }'
```

**Returns:** `201 Created` with the created perspective. Returns `400 Bad Request` when the statement has no usable result, `404 Not Found` when the statement does not exist, `409 Conflict` when the slug is taken, and `422 Unprocessable Entity` for an invalid body. A `409` response can include alternative slug suggestions.

***

## List accessible perspectives

**API endpoint:** GET /api/v1/perspectives

**Description:** Returns public perspectives and private ones you own or have been granted access to.

**Query parameters:**

| Parameter   | Default | Description                                             |
| ----------- | ------- | ------------------------------------------------------- |
| `is_public` | None    | Filter by public or private perspectives. Omit for all. |
| `limit`     | `50`    | Maximum results; range `1`–`100`.                       |
| `offset`    | `0`     | Results to skip.                                        |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/perspectives?limit=50&offset=0" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with accessible perspective summaries and pagination information.

***

## Check slug availability

**API endpoint:** HEAD /api/v1/perspectives/{slug}

**Description:** Check whether a slug is available before creating a perspective. This endpoint returns headers only. `200 OK` means the slug is taken. `404 Not Found` means the slug is available.

**Path params:**

| Parameter | Description                                                        |
| --------- | ------------------------------------------------------------------ |
| `slug`    | URL-friendly perspective identifier, for example `my-perspective`. |

**cURL:**

```bash
curl -sI https://$BASE_URL/api/v1/perspectives/monthly-revenue-by-store-region \
  -X HEAD \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:**

| Response        | Meaning                                                                                                                       |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `200 OK`        | Slug is already taken. `X-Perspective-Id`, `X-Perspective-Owner`, and `X-Perspective-Name` describe the existing perspective. |
| `404 Not Found` | Slug is available.                                                                                                            |

***

## Get perspective details

**API endpoint:** GET /api/v1/perspectives/{slug}

**Description:** Retrieve perspective metadata without downloading result rows. Use it to inspect the owner, underlying query, access settings, refresh behavior, and related links. If `auto_refresh` is enabled and data is stale, a refresh triggers automatically. Pass `?refresh=true` to force one.

**Path params:**

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `slug`    | URL-friendly perspective identifier. |

**Query parameters:**

| Parameter | Default | Description                                                                           |
| --------- | ------- | ------------------------------------------------------------------------------------- |
| `refresh` | `false` | Force a refresh even when the perspective is not stale or `auto_refresh` is disabled. |

**cURL:**

```bash
curl -s https://$BASE_URL/api/v1/perspectives/monthly-revenue-by-store-region \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` with perspective details. When a refresh starts, `X-Refresh-Statement-Id` identifies the new statement. Returns `403 Forbidden` when access is denied and `404 Not Found` when the perspective does not exist.

***

## Fetch perspective result

**API endpoint:** GET /api/v1/perspectives/{slug}/result

**Description:** Direct access to cached result data. Same format options as the statement result endpoint. If stale and `auto_refresh` is on, the current result is returned immediately while a background refresh starts.

**Path params:**

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `slug`    | URL-friendly perspective identifier. |

**Query parameters:**

| Parameter | Default            | Description                                                            |
| --------- | ------------------ | ---------------------------------------------------------------------- |
| `refresh` | `false`            | Force a background refresh before or while serving the current result. |
| `format`  | negotiated/default | Result format: `json`, `yaml`, `csv`, or `parquet`.                    |
| `limit`   | None               | Maximum rows for text formats.                                         |
| `offset`  | None               | Rows to skip for text formats.                                         |
| `columns` | None               | Comma-separated columns for text formats.                              |

**cURL:**

```bash
curl -s "https://$BASE_URL/api/v1/perspectives/monthly-revenue-by-store-region/result?format=json" \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `200 OK` for JSON, YAML, or CSV, and `307 Temporary Redirect` for Parquet. `Is-Stale: true` indicates the returned result is stale. `X-Refresh-Statement-Id` is present when a refresh starts. Returns `403 Forbidden` for denied access, `404 Not Found` when the perspective or result is unavailable, and `406 Not Acceptable` for an unsupported format.

***

## Update a perspective

**API endpoint:** PUT /api/v1/perspectives/{slug}

**Description:** Update an owned perspective. All fields are optional. Supplying a new `statement_id` replaces the underlying successful query result. Only the owner can update.

**Request body fields:** `name`, `description`, `tags`, `terms`, `statement_id`, `auto_refresh`, `is_public`, and `allowed_user_ids`.

**Path params:**

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `slug`    | URL-friendly perspective identifier. |

**Request body:**

```json
{
  "name": "<updated_name>",
  "auto_refresh": true,
  "is_public": false
}
```

**cURL:**

```bash
curl -s -X PUT https://$BASE_URL/api/v1/perspectives/monthly-revenue-by-store-region \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description", "auto_refresh": true}'
```

**Returns:** `201 Created` with the updated perspective. Returns `400 Bad Request` for an unusable replacement statement, `403 Forbidden` when the caller is not the owner, and `404 Not Found` when the perspective or statement does not exist.

***

## Delete a perspective

**API endpoint:** DELETE /api/v1/perspectives/{slug}

**Description:** Permanently removes the perspective. Only the owner can delete.

**Path params:**

| Parameter | Description                          |
| --------- | ------------------------------------ |
| `slug`    | URL-friendly perspective identifier. |

**cURL:**

```bash
curl -s -X DELETE https://$BASE_URL/api/v1/perspectives/monthly-revenue-by-store-region \
  -H "Authorization: Bearer $TOKEN"
```

**Returns:** `204 No Content` on success. Returns `403 Forbidden` when the caller is not the owner and `404 Not Found` when the perspective does not exist.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://v2.dataos.info/references/interfaces/apis/data-product-apis/api-reference/perspectives.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
