---
title: "Fetch the result of a DDSQL query"
method: POST
path: "/api/v2/ddsql/query/tabular/fetch"
tags: ["DDSQL"]
---

# Fetch the result of a DDSQL query

`POST /api/v2/ddsql/query/tabular/fetch`

## Request

- Base URL: `https://api.datadoghq.com`
- URL: `https://api.datadoghq.com/api/v2/ddsql/query/tabular/fetch`
- Auth: one of:
  - API key in header `DD-API-KEY` and API key in header `DD-APPLICATION-KEY`
  - OAuth 2
    - Authorization code: `/oauth2/v1/authorize`
    - Token URL: `/oauth2/v1/token` scopes: `timeseries_query`
- TypeScript: <https://skmtc.dev/datadog/apis/datadog-api-v2-collection/docs/api/v2/ddsql/query/tabular/fetch/post.ts> (a function with typed inputs; its response is checked against the schema)

Poll a previously submitted DDSQL query for results. Pass the opaque `query_id` returned
by a prior `ExecuteDdsqlTabularQuery` (or by a prior `FetchDdsqlTabularQuery` that
returned `state: running`) and the server returns either a `running` state to poll again
or a `completed` state with the column-major result set inlined.

For a scoped application key, include `timeseries_query` in its scopes.
Fetch results as the same user and organization that submitted the query.
The user or service account that owns the application key must have the data access
permissions required by the queried data sources through their roles.

## Request body

- DdsqlTabularQueryFetchRequest: Wrapper for a DDSQL tabular query fetch request.
  - `data` DdsqlTabularQueryFetchRequestData, required: JSON:API resource object for a DDSQL tabular query fetch request.
    - `attributes` DdsqlTabularQueryFetchRequestAttributes, required: Attributes describing which previously submitted DDSQL query to fetch.
      - `query_id` string, required: Opaque token returned by an earlier execute or fetch response that carried `state: running`. Identifies the query to poll for results.
    - `type` 'ddsql_query_fetch_request', required: JSON:API resource type for a DDSQL tabular query fetch request.

## Response `200`

OK

- DdsqlTabularQueryResponse: Response envelope for both the execute and fetch DDSQL tabular query endpoints. Carries the JSON:API primary resource and a top-level `meta` block with request-scoped observability handles.
  - `data` DdsqlTabularQueryResponseData, required: JSON:API resource object for a DDSQL tabular query response.
    - `attributes` DdsqlTabularQueryResponseAttributes, required: Attributes of a DDSQL tabular query response. `query_id` is set when `state` is `running`; `columns` is set when `state` is `completed`.
      - `columns` DdsqlTabularQueryColumn[]: Column-major result set. Each element carries one column's name, type, and values, with one value per row of the result. Set when `state` is `completed`.
        - `name` string, required: Name of the column as projected by the SQL statement.
        - `type` string, required: DDSQL data type of the column's values, for example `VARCHAR`, `BIGINT`, `DECIMAL`, `BOOLEAN`, `TIMESTAMP`, `JSON`, or an array variant such as `VARCHAR[]`. See the [DDSQL data-types reference](https://docs.datadoghq.com/ddsql_reference/#data-types) for the full, up-to-date list.
        - `values` unknown[], required: Column values in row order, one entry per result row. The element type follows the column's `type`. The following serialization rules should be taken into account: - `BIGINT` values are encoded as JSON numbers in the signed 64-bit integer range. - `DECIMAL` values are encoded as JSON numbers with 64-bit double precision. - `TIMESTAMP` and `DATE` values are encoded as Unix-millisecond integers; a `DATE` resolves to midnight UTC. - `JSON` values are returned as a JSON-encoded string. `null` is allowed for any column type where a value is missing.
          - unknown
      - `query_id` string: Opaque token to pass to the fetch endpoint to poll for results. Set when `state` is `running` and absent when `state` is `completed`.
      - `state` 'running' | 'completed', required: Lifecycle state of a DDSQL tabular query response. `running` means the query is still executing and the client should poll the fetch endpoint with the returned `query_id`. `completed` means the result set is inlined in `columns` and no further polling is required.
      - `warnings` string[]: Non-fatal messages emitted by the query engine while serving this response.
    - `id` string, required: Stable identifier for the query response resource.
    - `type` 'ddsql_query_response', required: JSON:API resource type for a DDSQL tabular query response.
  - `meta` DdsqlTabularQueryResponseMeta, required: Top-level JSON:API meta block accompanying every DDSQL tabular query response. Carries standard observability handles for client-side correlation.
    - `elapsed` integer, required: Server-side time spent serving this request, in milliseconds.
    - `request_id` string, required: Echo of the `DD-Request-ID` header assigned by Datadog's edge to this request, for support correlation.

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `429`: Too many requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/datadog/apis/datadog-api-v2-collection.md) - [All operations](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/llms.txt) - [OpenAPI document](https://skmtc.dev/datadog/apis/datadog-api-v2-collection/revisions/3f70db624329?raw)