> 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/advanced/query-lifecycle.md).

# Query lifecycle

Learn how asynchronous requests progress from submission to a final result or error.

REST, Semantic SQL, Metrics, and Source SQL use one asynchronous lifecycle. Separating submission from result download lets the API queue warehouse work, deduplicate identical queries, reuse successful results, and serve large Parquet files without keeping the original connection open.

GraphQL normally completes this lifecycle inside one request. If it returns `202`, follow its retry guidance.

```mermaid
flowchart LR
    A["Submit query"] --> B["202 Accepted + statement ID"]
    B --> C["Poll statement status"]
    C --> D{"Status"}
    D -->|"ACCEPTED / QUEUED / IN_PROGRESS"| C
    D -->|"SUCCESS"| E["Fetch result"]
    D -->|"FAILED"| F["Inspect error"]
```

{% hint style="info" %}
**Deep dive:** the flow above is the short version. [Statement lifecycle](https://v2.dataos.info/references/interfaces/apis/data-product-apis/querying-data-products/advanced/statement-lifecycle.md) walks through the same states as detailed sequence diagrams (Client ↔ API ↔ Queue ↔ Worker ↔ Object Store) for the standard flow, the error path, deduplication, and the GraphQL timeout path. Use it when you need to see exactly which component does what at each step.
{% endhint %}

## 1. Submit

| Method        | Endpoint                                           |
| ------------- | -------------------------------------------------- |
| Semantic REST | `POST /api/v1/query/semantic/rest`                 |
| Semantic SQL  | `POST /api/v1/query/semantic/sql`                  |
| Named metric  | `GET` or `POST /api/v1/query/metric/{metric_name}` |
| Source SQL    | `POST /api/v1/query/statement`                     |

An executable request returns `202 Accepted`, a statement `id`, and a `Location` header. Persist the ID.

```json
{
  "id": "stmt_abc123",
  "status": "QUEUED",
  "strategy": "EXECUTE",
  "fingerprint": "...",
  "is_stale": false,
  "_links": {
    "self": {"href": "/api/v1/query/statement/stmt_abc123"}
  }
}
```

## 2. Read the execution strategy

| Strategy        | Meaning                                                         | Client action                                       |
| --------------- | --------------------------------------------------------------- | --------------------------------------------------- |
| `EXECUTE`       | A new warehouse execution was queued.                           | Poll this statement.                                |
| `AWAIT_PRIMARY` | An identical query is already running; this request follows it. | Poll normally; do not resubmit.                     |
| `REUSE_RESULT`  | A previous successful result can be reused.                     | Status can already be `SUCCESS`; fetch immediately. |

Branch on `status` and `_links`; do not assume every accepted request starts a warehouse query.

## 3. Poll

```bash
curl "$BASE_URL/query/statement/stmt_abc123" \
  --header "Authorization: Bearer $TOKEN"
```

| Status        | Meaning                                         |
| ------------- | ----------------------------------------------- |
| `ACCEPTED`    | Received but not yet queued.                    |
| `QUEUED`      | Waiting for a worker.                           |
| `IN_PROGRESS` | Running against the warehouse.                  |
| `SUCCESS`     | Result is available.                            |
| `FAILED`      | Execution ended with an error; inspect `error`. |

Stop polling on `SUCCESS` or `FAILED`. Use bounded exponential backoff instead of polling continuously. Do not call `/result` after `FAILED`.

## 4. Fetch

After `SUCCESS`:

```bash
curl "$BASE_URL/query/statement/stmt_abc123/result?format=json&limit=100&offset=0" \
  --header "Authorization: Bearer $TOKEN"
```

| Format    | Behavior                                                                                              |
| --------- | ----------------------------------------------------------------------------------------------------- |
| `parquet` | Default. Returns `307` to a presigned object-store URL. `limit`, `offset`, and `columns` are ignored. |
| `json`    | Inline `cols`, `rows`, `types`, `row_count`, `size_bytes`, and links.                                 |
| `csv`     | Inline CSV text.                                                                                      |
| `yaml`    | Inline YAML.                                                                                          |

For text formats, `columns=store_region,total_revenue` projects columns and `limit` / `offset` paginate rows. Follow redirects when downloading Parquet.

## Handle staleness

`is_stale: true` or `Is-Stale: true` means one or more dependent models have pending intervals. The query still succeeded; its result may not include the latest expected data. Show freshness separately from execution status.

## Retry safely

Poll the existing ID for normal retries. The server already deduplicates identical in-flight queries and can reuse successful results.

Use `?retry_on_recent_failure=true` only when deliberately rerunning an identical query that failed recently. Semantic REST and Semantic SQL also accept `?transpile_only=true`; this returns `200` with compiled SQL, creates no statement, and has no poll or fetch stage.

## GraphQL exception

GraphQL returns inline `data` and execution metadata under `extensions` when it finishes within the wait window. If it returns `202`, respect `Retry-After` and resend the identical GraphQL request or poll `extensions._links.self`. Deduplication prevents a second warehouse execution.


---

# 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/advanced/query-lifecycle.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.
