--- title: Fetch the result of a DDSQL query description: Datadog, the leading service for cloud-scale monitoring. breadcrumbs: Docs > API Reference > DDSQL --- > For the complete documentation index, see [llms.txt](https://docs.datadoghq.com/llms.txt). # Fetch the result of a DDSQL query{% #fetch-the-result-of-a-ddsql-query %} {% tab title="v2" %} | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------- | | ap1.datadoghq.com | POST https://api.ap1.datadoghq.com/api/v2/ddsql/query/tabular/fetch | | ap2.datadoghq.com | POST https://api.ap2.datadoghq.com/api/v2/ddsql/query/tabular/fetch | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/ddsql/query/tabular/fetch | | app.ddog-gov.com | POST https://api.ddog-gov.com/api/v2/ddsql/query/tabular/fetch | | us2.ddog-gov.com | POST https://api.us2.ddog-gov.com/api/v2/ddsql/query/tabular/fetch | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/api/v2/ddsql/query/tabular/fetch | | app.datadoghq.com | POST https://api.datadoghq.com/api/v2/ddsql/query/tabular/fetch | | us3.datadoghq.com | POST https://api.us3.datadoghq.com/api/v2/ddsql/query/tabular/fetch | | us5.datadoghq.com | POST https://api.us5.datadoghq.com/api/v2/ddsql/query/tabular/fetch | ### Overview 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. This endpoint requires the `timeseries_query` permission. OAuth apps require the `timeseries_query` authorization [scope](https://docs.datadoghq.com/api/latest/scopes.md#ddsql) to access this endpoint. ### Request #### Body Data (required) {% tab title="Model" %} | Parent field | Field | Type | Description | | ------------ | ---------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API resource object for a DDSQL tabular query fetch request. | | data | attributes [*required*] | object | Attributes describing which previously submitted DDSQL query to fetch. | | attributes | query_id [*required*] | string | Opaque token returned by an earlier execute or fetch response that carried `state: running`. Identifies the query to poll for results. | | data | type [*required*] | enum | JSON:API resource type for a DDSQL tabular query fetch request. Allowed enum values: `ddsql_query_fetch_request` | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==" }, "type": "ddsql_query_fetch_request" } } ``` {% /tab %} ### Response {% tab title="200" %} OK {% tab title="Model" %} 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. | Parent field | Field | Type | Description | | ------------ | ---------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | data [*required*] | object | JSON:API resource object for a DDSQL tabular query response. | | data | attributes [*required*] | object | Attributes of a DDSQL tabular query response. `query_id` is set when `state` is `running`; `columns` is set when `state` is `completed`. | | attributes | columns | [object] | 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`. | | columns | name [*required*] | string | Name of the column as projected by the SQL statement. | | columns | type [*required*] | string | 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.md#data-types) for the full, up-to-date list. | | columns | values [*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: | `null` is allowed for any column type where a value is missing. | | attributes | 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`. | | attributes | state [*required*] | enum | 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. Allowed enum values: `running,completed` | | attributes | warnings | [string] | Non-fatal messages emitted by the query engine while serving this response. | | data | id [*required*] | string | Stable identifier for the query response resource. | | data | type [*required*] | enum | JSON:API resource type for a DDSQL tabular query response. Allowed enum values: `ddsql_query_response` | | | meta [*required*] | object | Top-level JSON:API meta block accompanying every DDSQL tabular query response. Carries standard observability handles for client-side correlation. | | meta | elapsed [*required*] | int64 | Server-side time spent serving this request, in milliseconds. | | meta | request_id [*required*] | string | Echo of the `DD-Request-ID` header assigned by Datadog's edge to this request, for support correlation. | {% /tab %} {% tab title="Example" %} ```json { "data": { "attributes": { "columns": [ { "name": "service", "type": "VARCHAR", "values": [ "web-store", "checkout" ] } ], "query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==", "state": "completed", "warnings": [ "Query result was truncated at the configured row_limit." ] }, "id": "00000000-0000-0000-0000-000000000000", "type": "ddsql_query_response" }, "meta": { "elapsed": 87, "request_id": "req-7f3e7d2c-1a0b-4d3e-9b2a-3c4d5e6f7082" } } ``` {% /tab %} {% /tab %} {% tab title="400" %} Bad Request {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="403" %} Forbidden {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} {% tab title="429" %} Too many requests {% tab title="Model" %} API error response. | Field | Type | Description | | ------------------------ | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tab %} {% tab title="500" %} Internal Server Error {% tab title="Model" %} API error response. | Parent field | Field | Type | Description | | ------------ | ------------------------ | -------- | ------------------------------------------------------------------------------- | | | errors [*required*] | [object] | A list of errors. | | errors | detail | string | A human-readable explanation specific to this occurrence of the error. | | errors | meta | object | Non-standard meta-information about the error | | errors | source | object | References to the source of the error. | | source | header | string | A string indicating the name of a single request header which caused the error. | | source | parameter | string | A string indicating which URI query parameter caused the error. | | source | pointer | string | A JSON pointer to the value in the request document that caused the error. | | errors | status | string | Status code of the response. | | errors | title | string | Short human-readable summary of the error. | {% /tab %} {% tab title="Example" %} ```json { "errors": [ { "detail": "Missing required attribute in body", "meta": {}, "source": { "header": "Authorization", "parameter": "limit", "pointer": "/data/attributes/title" }, "status": "400", "title": "Bad Request" } ] } ``` {% /tab %} {% /tab %} ### Code Example ##### \## default # \# Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" \# Curl command curl -X POST "https://api.datadoghq.com/api/v2/ddsql/query/tabular/fetch" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${DD_BEARER_TOKEN}" \ -d @- << EOF { "data": { "attributes": { "query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==" }, "type": "ddsql_query_fetch_request" } } EOF {% /tab %}