--- cuppy_hub: salesforce cuppy_path: reference/official/data360/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.md cuppy_section: docs cuppy_doc: V484-RY4G cuppy_doc_uuid: 7de4e960-6d78-49f4-8246-fd3056a4928e cuppy_permalink: https://cuppy.io/salesforce/d/V484-RY4G cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/salesforce/docs/reference/official/data360/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 400232e7728fe6e39a925fccaecb22862ab8215e548a47ac8d2b3cdcf693c013 # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- > Mirror of (Salesforce, Data 360 Query Guide), read 2026-10-23. Salesforce's own page is the authority; this copy exists because that site refuses non-browser readers. ## 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. This API is the recommended interface for new integrations. See [Migrate from Query API V1 and V2](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-migration.html) for guidance on updating existing code. * **HTTP Method**: POST * **Format**: REST * **URI**: `/api/v3/query` | Header | Value | | --- | --- | | `Authorization` | `Bearer {accessToken}` | | `Content-Type` | `application/json` | | `Accept` | `application/json` (default) or `application/vnd.apache.arrow.stream` | | Field | Type | Required | Description | | --- | --- | --- | --- | | `sql` | string | Yes | SQL query to execute. Uses Data 360 SQL syntax. | | `transferMode` | string | No | Execution mode. Accepted values: `ASYNC`, `ADAPTIVE` (default). | | `paramStyle` | string | No | Parameter binding style. Accepted values: `QUESTION_MARK` (default), `NAMED`, `DOLLAR_NUMBERED`. See [Parameterized Queries](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.html#parameterized-queries). | | `parameters` | array | No | Array of parameter objects for parameterized queries. Each object requires `type` (a Data 360 SQL type name) and `value` (a JSON string). See [Parameterized Queries](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.html#parameterized-queries). | | `settings` | object | No | See [Query Settings](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/query-api-v3-post.html#query-settings) for supported keys. | | `resultRange` | object | No | Controls what is returned within the REST response. ADAPTIVE mode only. Supported keys: `rowLimit` (integer), `byteLimit` (integer, default and maximum 20 MB). | | `queryRowLimit` | integer | No | Maximum number of rows to produce by the query. Acts as an implicit `LIMIT` clause. The query won’t produce more rows than this value. Set to `0` to retrieve only the schema without producing any rows. | The `settings` object accepts the following keys: * `timezone` — Time zone identifier for date and time values, for example `"Etc/UTC"`. * `language` — Language identifier for locale-specific formatting, for example `"de_DE"`. * `date_style` — Order of year, month, and day for parsing date strings. Accepted values: `MDY`, `DMY`, `YMD`. See [Date/Time Input](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/datetime.html#date-time-input). * `lc_time` — Locale for date literals, as an ISO language and country code, for example `"en_US"` or `"de_AT"`. * `query_timeout` — Execution limit in milliseconds before the query is terminated, for example `1800000` (30 minutes). 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](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/dc-sql-reference/datatypes.html) 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`. `type` takes SQL type names, not JSON type names. Use `varchar` rather than `string`. Both ASYNC and ADAPTIVE modes share a common response structure. Both ASYNC and ADAPTIVE modes return these response headers. | Header | Description | | --- | --- | | `Date` | Timestamp when the response was generated. | | `Content-Type` | `application/json` or `application/vnd.apache.arrow.stream` depending on the `Accept` request header. | | `x-hyperdb-status` | JSON-serialized string containing the full query status. Fields: `queryId`, `completionStatus`, `chunkCount`, `rowCount`, `progress`, `expirationTime`, and `executionStats`. Use the `queryId` from this header to poll for results. | 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. | Field | Description | | --- | --- | | `metadata` | Object containing column schema | | `data` | Omitted in ASYNC mode | | `returnedRows` | Always `0` in ASYNC mode | 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. | Field | Description | | --- | --- | | `metadata` | Object containing column schema | | `data` | Array of result rows (each row is an array); omitted if adaptive timeout reached | | `returnedRows` | Number of rows returned (`0` if adaptive timeout reached) | These examples show ASYNC and ADAPTIVE requests and responses. Response headers (excerpt): Response body: This ADAPTIVE request binds two parameters. The `paramStyle` is `QUESTION_MARK`, so each `?` placeholder is filled from the `parameters` array in order. This ADAPTIVE request sets `date_style`, `lc_time`, and `query_timeout` to control date parsing, locale, and the execution timeout. Without an explicit `date_style`, the `01/08/1999` literal is ambiguous. 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](https://arrow.apache.org/docs/python/) or the [Apache Arrow Java library](https://arrow.apache.org/docs/java/)) 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. | Status | Meaning | | --- | --- | | 400 | Invalid SQL or request payload | | 401 | Missing or invalid authentication | | 408 | Request timed out | | 429 | Rate limit exceeded | | 500 | Internal server error | Error responses include a rich error model with SQLSTATE codes and human-readable detail. 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](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-statuscodes.html) for the full reference. * [Query Data using Query API](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-overview.html) — Connect REST API (recommended for most integrations) * [Query V1 and V2 API](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-legacy.html) — Legacy API reference * [Query Services Status Codes](https://developer.salesforce.com/docs/data/data-cloud-query-guide/references/data-cloud-query-api-reference/c360a-api-queryservices-statuscodes.html) — Error code reference * [API Limits and Guidelines](https://help.salesforce.com/s/articleView?id=data.c360_a_limits_and_guidelines.htm&type=5) --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 376 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/salesforce/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.