Submit SQL Query

Use the POST /api/v3/query endpoint of the Data 360 Query API to execute a SQL query against your Data 360 data. Submit a query in ASYNC mode to receive a queryId for polling, or use ADAPTIVE mode to receive results immediately when the query completes quickly. Both modes support JSON and Apache Arrow response formats.

• HTTP Method: POST
• Format: REST
• URI: /api/v3/query

The paramStyle request field controls how parameters are bound in your SQL:

• QUESTION_MARK (default) — Use ? placeholders
• NAMED — Use named placeholders (:paramName)
• DOLLAR_NUMBERED — Use positional placeholders ($1, $2, …)

Each object in the parameters array requires a type and a value.

• type — A Data 360 SQL type name, such as varchar, bigint, or boolean. For types that take a length or precision, include the relevant field, for example { "type": "varchar", "length": 10, "value": "abc" }.
• value — The parameter value, always passed as a JSON string. Even for numeric types, pass the value as a string, for example "42", not 42.

Both ASYNC and ADAPTIVE modes share a common response structure.

Both ASYNC and ADAPTIVE modes return these response headers.

In ASYNC mode, the response body omits the data field and returnedRows is 0. Use the queryId from the x-hyperdb-status response header to poll GET /api/v3/query/{queryId} for completion.

If the query completes within the adaptive timeout, data contains the result rows. If the query exceeds the adaptive timeout without producing rows, the response mimics ASYNC mode: the data field is omitted and returnedRows is 0. Use the queryId from the x-hyperdb-status response header to poll GET /api/v3/query/{queryId} for completion.

These examples show ASYNC and ADAPTIVE requests and responses.

1POST https://{dne_cdpInstanceUrl}/api/v3/query
2Authorization: Bearer {accessToken}
3Content-Type: application/json
4
5{
6  "sql": "SELECT ssot__FirstName__c, ssot__LastName__c FROM ssot__Individual__dlm LIMIT 10",
7  "transferMode": "ASYNC"
8}

Response headers (excerpt):

1x-hyperdb-status: {"queryId":"MTAuMjcuMTgxLjE0OTo3NDg0_1cfc8d35-464c-9185-1f41-3eb638a71f7a","completionStatus":"RUNNING","chunkCount":0,"rowCount":0,"progress":0.0,"expirationTime":"2025-09-26T10:55:07.438Z","executionStats":{"wallClockTime":0.0,"rowsProcessed":0}}

Response body:

1{
2    "metadata": {
3        "columns": [
4            {
5                "name": "ssot__FirstName__c",
6                "type": "varchar",
7                "nullable": true
8            },
9            { "name": "ssot__LastName__c", "type": "varchar", "nullable": true }
10        ]
11    },
12    "returnedRows": 0
13}

1POST https://{dne_cdpInstanceUrl}/api/v3/query
2Authorization: Bearer {accessToken}
3Content-Type: application/json
4
5{
6  "sql": "SELECT ssot__FirstName__c, ssot__LastName__c FROM ssot__Individual__dlm LIMIT 10",
7  "transferMode": "ADAPTIVE"
8}

1{
2  "metadata": {
3    "columns": [
4      {
5        "name": "ssot__FirstName__c",
6        "type": "varchar",
7        "nullable": true
8      },
9      { "name": "ssot__LastName__c", "type": "varchar", "nullable": true }
10    ]
11  },
12  "data": [
13    ["Alice", "Johnson"],
14    ["Bob", "Smith"]
15  ],
16  "returnedRows": 2
17}

This ADAPTIVE request binds two parameters. The paramStyle is QUESTION_MARK, so each ? placeholder is filled from the parameters array in order.

1POST https://{dne_cdpInstanceUrl}/api/v3/query
2Authorization: Bearer {accessToken}
3Content-Type: application/json
4
5{
6  "sql": "SELECT ssot__FirstName__c, ssot__LastName__c FROM ssot__Individual__dlm WHERE ssot__CountryCode__c = ? AND ssot__Age__c >= ? LIMIT 10",
7  "transferMode": "ADAPTIVE",
8  "paramStyle": "QUESTION_MARK",
9  "parameters": [
10    { "type": "varchar", "value": "US" },
11    { "type": "bigint", "value": "18" }
12  ]
13}

Set Accept: application/vnd.apache.arrow.stream to request a binary Arrow IPC stream instead of JSON. Use an Arrow-compatible client library (such as PyArrow or the Apache Arrow Java library) to read the stream.

In ASYNC mode, the response body always contains only schema metadata with no data rows, regardless of the Accept header. Retrieve the queryId from the x-hyperdb-status response header and poll GET /api/v3/query/{queryId} for completion, then use GET /api/v3/query/{queryId}/rows or /chunks/{chunkId} with Accept: application/vnd.apache.arrow.stream to retrieve results.

Set Accept: application/vnd.apache.arrow.stream to receive an inline ADAPTIVE result as a binary Arrow IPC stream. If the query exceeds the adaptive timeout and falls back to ASYNC mode, the response body contains only schema metadata with no data rows. Retrieve the queryId from the x-hyperdb-status response header and poll GET /api/v3/query/{queryId} for completion.

V3 returns structured error objects with HTTP status codes.

Error responses include a rich error model with SQLSTATE codes and human-readable detail.

1{
2  "error": "42601",
3  "message": "syntax error [TraceId:03d7d84a302b827ea8f0fe1d251f4eaf]",
4  "details": {
5    "customerDetail": "line 1, column 49: ...",
6    "errorSource": "User",
7    "position": {
8      "errorBeginCharacterOffset": "48",
9      "errorEndCharacterOffset": "53"
10    }
11  }
12}

The position field is included for syntax errors. errorSource indicates whether the error originated from user input ("User") or the system. See Query Services Status Codes for the full reference.

• Query Data using Query API — Connect REST API (recommended for most integrations)
• Query V1 and V2 API — Legacy API reference
• Query Services Status Codes — Error code reference
• API Limits and Guidelines