--- title: Fetch the result of a DDSQL query description: Poll a previously submitted DDSQL query for results. breadcrumbs: Docs > API > Fetch the result of a DDSQL query --- > For the complete documentation index, see [llms.txt](https://dnd37xeb23o8n.cloudfront.net/stefon.simmons/docs-astro-web-10435/llms.txt). # Fetch the result of a DDSQL query ## v2 (latest) | Datadog site | API endpoint | | ----------------- | ------------------------------------------------------------------- | | 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 | | app.datadoghq.eu | POST https://api.datadoghq.eu/api/v2/ddsql/query/tabular/fetch | | 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 | | uk1.datadoghq.com | POST https://api.uk1.datadoghq.com/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 | ### 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://dnd37xeb23o8n.cloudfront.net/stefon.simmons/docs-astro-web-10435/api/latest/scopes.md#ddsql) to access this endpoint. ### Request #### Body Data (required) {% tabs %} {% tab label="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`. Default: `ddsql_query_fetch_request`. | {% /tab %} {% tab label="Example" %} ```json { "data": { "attributes": { "query_id": "eyJxdWVyeSI6ICJTRUxFQ1QgKiBGUk9NIGxvZ3MifQ==" }, "type": "ddsql_query_fetch_request" } } ``` {% /tab %} {% /tabs %} ### Response {% tabs %} {% tab label="200" %} OK {% tabs %} {% tab label="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*] | [any] | 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. | | 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`. Default: `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 label="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 %} {% /tabs %} {% /tab %} {% tab label="400" %} Bad Request {% tabs %} {% tab label="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 label="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 %} {% /tabs %} {% /tab %} {% tab label="403" %} Forbidden {% tabs %} {% tab label="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 label="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 %} {% /tabs %} {% /tab %} {% tab label="429" %} Too many requests {% tabs %} {% tab label="Model" %} API error response. | Field | Type | Description | | ------------------- | -------- | ----------------- | | errors [*required*] | [string] | A list of errors. | {% /tab %} {% tab label="Example" %} ```json { "errors": [ "Bad Request" ] } ``` {% /tab %} {% /tabs %} {% /tab %} {% tab label="500" %} Internal Server Error {% tabs %} {% tab label="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 label="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 %} {% /tabs %} {% /tab %} {% /tabs %} ### Code Example {% tabs %} {% tab label="Curl" %} ```bash # Set your Datadog site and credentials export DD_SITE="datadoghq.com" # Or us3.datadoghq.com, us5.datadoghq.com, datadoghq.eu, ap1.datadoghq.com, ap2.datadoghq.com, uk1.datadoghq.com, ddog-gov.com, us2.ddog-gov.com # Use a Personal Access Token or Service Access Token export DD_BEARER_TOKEN="" curl -X POST "https://api.${DD_SITE}/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 %} {% /tabs %}