Execute a tabular DDSQL query
https://api.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.us3.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.us5.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.datadoghq.eu/api/v2/ddsql/query/tabularhttps://api.ap1.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.ap2.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.uk1.datadoghq.com/api/v2/ddsql/query/tabularhttps://api.ddog-gov.com/api/v2/ddsql/query/tabularhttps://api.us2.ddog-gov.com/api/v2/ddsql/query/tabularOverview
Submit a DDSQL statement and return either a running state with an opaque query_id
for the client to poll, or a completed state with the column-major result set inlined
when the query finishes quickly enough to be served synchronously.
For a scoped application key, include timeseries_query in its scopes.
A query that does not read a data source, such as SELECT 1, requires no additional
data-source permissions. Queries that read data sources also require the user or
service account that owns the application key to have the corresponding data access
permissions through their roles. The timeseries_query permission does not grant
access to the underlying data sources.
OAuth apps require the timeseries_query authorization scope to access this endpoint.
Request
Body Data (required)
data [required]JSON:API resource object for a DDSQL tabular query execution request.
attributes [required]Attributes describing the DDSQL query to execute.
query [required]The DDSQL statement to execute. DDSQL is Datadog's SQL dialect, which is a subset of PostgreSQL, scoped to Datadog data sources.
row_limitCap on the number of rows returned. Defaults to 5,000 when omitted. Must be between 1 and 10,000 inclusive; values outside this range are rejected with 400.
time [required]Time window scoping the underlying data sources, expressed in Unix milliseconds
since the epoch. Inclusive on from_timestamp, exclusive on to_timestamp.
Results from static tables (for example, dd.hosts) are not affected by the
time window, but the field must still be provided.
from_timestamp [required]Start of the query window (inclusive), in Unix milliseconds since the epoch.
to_timestamp [required]End of the query window (exclusive), in Unix milliseconds since the epoch.
type [required]JSON:API resource type for a DDSQL tabular query request.
ddsql_query_requestddsql_query_request{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}Response
OK
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 [required]JSON:API resource object for a DDSQL tabular query response.
attributes [required]Attributes of a DDSQL tabular query response. query_id is set when
state is running; columns is set when state is completed.
columnsColumn-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 [required]Name of the column as projected by the SQL statement.
type [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
for the full, up-to-date list.
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:
BIGINTvalues are encoded as JSON numbers in the signed 64-bit integer range.DECIMALvalues are encoded as JSON numbers with 64-bit double precision.TIMESTAMPandDATEvalues are encoded as Unix-millisecond integers; aDATEresolves to midnight UTC.JSONvalues are returned as a JSON-encoded string.
null is allowed for any column type where a value is missing.
query_idOpaque token to pass to the fetch endpoint to poll for results.
Set when state is running and absent when state is completed.
state [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.
running, completedwarningsNon-fatal messages emitted by the query engine while serving this response.
id [required]Stable identifier for the query response resource.
type [required]JSON:API resource type for a DDSQL tabular query response.
ddsql_query_responseddsql_query_responsemeta [required]Top-level JSON:API meta block accompanying every DDSQL tabular query response. Carries standard observability handles for client-side correlation.
elapsed [required]Server-side time spent serving this request, in milliseconds.
request_id [required]Echo of the DD-Request-ID header assigned by Datadog's edge to this request,
for support correlation.
{
"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"
}
}Bad Request
API error response.
errors [required]A list of errors.
detailA human-readable explanation specific to this occurrence of the error.
metaNon-standard meta-information about the error
sourceReferences to the source of the error.
headerA string indicating the name of a single request header which caused the error.
parameterA string indicating which URI query parameter caused the error.
pointerA JSON pointer to the value in the request document that caused the error.
statusStatus code of the response.
titleShort human-readable summary of the error.
{
"errors": [
{
"detail": "Missing required attribute in body",
"meta": {},
"source": {
"header": "Authorization",
"parameter": "limit",
"pointer": "/data/attributes/title"
},
"status": "400",
"title": "Bad Request"
}
]
}Forbidden
API error response.
errors [required]A list of errors.
detailA human-readable explanation specific to this occurrence of the error.
metaNon-standard meta-information about the error
sourceReferences to the source of the error.
headerA string indicating the name of a single request header which caused the error.
parameterA string indicating which URI query parameter caused the error.
pointerA JSON pointer to the value in the request document that caused the error.
statusStatus code of the response.
titleShort human-readable summary of the error.
{
"errors": [
{
"detail": "Missing required attribute in body",
"meta": {},
"source": {
"header": "Authorization",
"parameter": "limit",
"pointer": "/data/attributes/title"
},
"status": "400",
"title": "Bad Request"
}
]
}Too many requests
API error response.
errors [required]A list of errors.
{
"errors": [
"Bad Request"
]
}Internal Server Error
API error response.
errors [required]A list of errors.
detailA human-readable explanation specific to this occurrence of the error.
metaNon-standard meta-information about the error
sourceReferences to the source of the error.
headerA string indicating the name of a single request header which caused the error.
parameterA string indicating which URI query parameter caused the error.
pointerA JSON pointer to the value in the request document that caused the error.
statusStatus code of the response.
titleShort human-readable summary of the error.
{
"errors": [
{
"detail": "Missing required attribute in body",
"meta": {},
"source": {
"header": "Authorization",
"parameter": "limit",
"pointer": "/data/attributes/title"
},
"status": "400",
"title": "Bad Request"
}
]
}Code Example
# Set your Datadog site and credentials
export DD_SITE="datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us3.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us5.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="datadoghq.eu"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ap1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ap2.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="uk1.datadoghq.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF# Set your Datadog site and credentials
export DD_SITE="us2.ddog-gov.com"
# Use a Personal Access Token or Service Access Token
export DD_BEARER_TOKEN="<PERSONAL_ACCESS_TOKEN OR SERVICE_ACCESS_TOKEN>"
curl -X POST "https://api.${DD_SITE}/api/v2/ddsql/query/tabular" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ${DD_BEARER_TOKEN}" \
-d @- << EOF
{
"data": {
"attributes": {
"query": "SELECT cloud_provider, count(*) FROM dd.hosts group by cloud_provider",
"row_limit": 1000,
"time": {
"from_timestamp": 1736942400000,
"to_timestamp": 1736946000000
}
},
"type": "ddsql_query_request"
}
}
EOF