> 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/querying-data-products/perspectives.md).

# Perspectives

Turn a successful query into a reusable, governed data asset.

A perspective turns a successful query into a named, reusable data asset. It stores the query context, exposes the latest result through a human-readable slug, and adds ownership, visibility, allow-listing, and refresh behavior.

Use a perspective for a shared reporting slice or recurring result. Do not use it as a substitute for a governed metric: a **metric** standardizes a business calculation; a **perspective** standardizes access to a saved query result.

## Create a perspective

First submit a REST, Semantic SQL, Metric, or Source SQL query and wait for statement status `SUCCESS`. Then save that statement:

```bash
curl --request POST "$BASE_URL/perspectives" \
  --header "Authorization: Bearer $TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "Monthly revenue by store region",
    "slug": "monthly-revenue-by-store-region",
    "description": "Governed monthly revenue split by store region.",
    "statement_id": "stmt_abc123",
    "auto_refresh": true,
    "is_public": false
  }'
```

`name` and `statement_id` are required. If `slug` is omitted, the API derives it from the name. The source statement must exist, be successful, and have a result. A duplicate slug returns `409` with suggested alternatives.

## Fetch a result

```bash
curl "$BASE_URL/perspectives/monthly-revenue-by-store-region/result?format=json&limit=100" \
  --header "Authorization: Bearer $TOKEN"
```

Supported formats are `json`, `yaml`, `csv`, and `parquet`. Parquet is the default and returns a `307` redirect to a presigned URL. Text formats support `limit`, `offset`, and comma-separated `columns`.

## Understand refresh behavior

With `auto_refresh: true`, reading a stale perspective triggers a refresh in the background while the API returns the current cached result.

* `Is-Stale: true` means the returned result may not contain the latest expected data.
* `X-Refresh-Statement-Id` identifies the background refresh statement.

Force a refresh even when automatic refresh is disabled:

```
GET /api/v1/perspectives/{slug}?refresh=true
GET /api/v1/perspectives/{slug}/result?refresh=true
```

Track the ID from `X-Refresh-Statement-Id` through the statement endpoints. See [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md).

## Manage perspectives

| Operation       | Request                                                     | Notes                                                                                                    |
| --------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| Check a slug    | `HEAD /api/v1/perspectives/{slug}`                          | Returns `200` when an accessible perspective exists; otherwise `404`.                                    |
| List accessible | `GET /api/v1/perspectives?is_public=true&limit=50&offset=0` | Includes public perspectives and private perspectives you own or can access. Maximum page size is `100`. |
| Inspect         | `GET /api/v1/perspectives/{slug}`                           | Returns metadata, saved query context, access controls, and links.                                       |
| Update          | `PUT /api/v1/perspectives/{slug}`                           | Owner only. Partial update; a new `statement_id` must be successful.                                     |
| Delete          | `DELETE /api/v1/perspectives/{slug}`                        | Owner only; returns `204`.                                                                               |

The list response stores records in `items` and paging state in `pagination`.

{% hint style="info" %}
Perspectives preserve the query type and source context behind the statement. Consumers read the stable perspective slug; owners can update it to a newer successful statement without changing that consumer URL.
{% endhint %}

## Next steps

* Follow the [Query lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/query-lifecycle.md) to monitor perspective refresh statements.
* Use [Metrics](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/metrics.md) when consumers need a standardized KPI rather than a saved query result.


---

# 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/querying-data-products/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.
