> 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/concepts/foundations/activation/apis/api-reference/perspectives.md).

# Perspectives

Save a query result as a named, shareable view. Perspectives auto-refresh when underlying data changes.

## Typical Workflow

1. Submit any query and wait for `SUCCESS`.
2. Create a perspective via `POST /perspectives` with the `statement_id`.
3. Share the slug URL — `GET /perspectives/{slug}/result`.
4. Auto-refresh keeps results fresh when upstream data changes (if `auto_refresh: true`).

***

## POST /api/v1/perspectives

**Summary:** Create a perspective

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

**cURL:**

```bash
curl -s -X POST https://$BASE_URL/api/v1/perspectives \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MAU by Region",
    "statement_id": "stmt_abc123",
    "slug": "mau-by-region",
    "auto_refresh": true,
    "is_public": false
  }'
```

**Returns:** HTTP 201 with the created perspective object. HTTP 409 if slug is taken (response includes alternative slug suggestions).

***

## GET /api/v1/perspectives

**Summary:** List accessible perspectives

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

**cURL:**

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

**Returns:** JSON with `items[]` — each item has `slug`, `name`, `owner`, `is_public`, `auto_refresh`, `created_at`, and `_links`.

***

## HEAD /api/v1/perspectives/{slug}

**Summary:** Check slug availability

**Description:** 200 = slug is taken (headers include `X-Perspective-Id`, `X-Perspective-Owner`, `X-Perspective-Name`). 404 = slug is available.

**cURL:**

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

**Returns:** **200** — Slug exists. Check `X-Perspective-*` response headers. **404** — Slug is free to use.

***

## GET /api/v1/perspectives/{slug}

**Summary:** Get perspective details

**Description:** Full metadata including underlying query, access settings, and HATEOAS links. If `auto_refresh` is on and data is stale, a refresh triggers automatically. Pass `?refresh=true` to force one.

**cURL:**

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

**Returns:** Full `PerspectiveDetail` object: `id`, `slug`, `name`, `sql_query`, `auto_refresh`, `is_public`, `allowed_user_ids[]`, `created_at`, `_links`.

***

## GET /api/v1/perspectives/{slug}/result

**Summary:** Fetch perspective 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.

**cURL:**

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

**Returns:** Same as statement result: `cols[]`, `rows[][]`, `types[]`, `row_count`. `Is-Stale: true` header if result is stale. `X-Refresh-Statement-Id` header if a refresh was triggered.

***

## PUT /api/v1/perspectives/{slug}

**Summary:** Update a perspective

**Description:** Update name, description, access settings, or underlying query (via a new `statement_id`). All fields are optional. Only the owner can update.

**cURL:**

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

**Returns:** HTTP 201 with the updated perspective. HTTP 403 if you are not the owner.

***

## DELETE /api/v1/perspectives/{slug}

**Summary:** Delete a perspective

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

**cURL:**

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

**Returns:** HTTP 204 — no response body. HTTP 403 if not owner. HTTP 404 if not found.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://v2.dataos.info/concepts/foundations/activation/apis/api-reference/perspectives.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.