Query API V2 Call Overview

Query API V2 supports SQL query in ANSI standard. The results return as an array of records. The expected input when calling this API is SQL. The input objects include data stream, profile and engagement data model objects, and unified data model objects. You can use Query API V2 to support a variety of use cases, which includes large volume data reads, external application integration, or interactive online querying on the data lake.

  • SQL Support: Execute ANSI standard SQL queries against your Data Cloud data
  • Cursor Pagination: Support for forward-only cursor pagination
  • Dual Endpoints: Support for both GET and POST API calls
  • Large Data Sets: Ideal for large volume data reads and external application integration
  • Browser Compatibility: Suitable for browser-based clients with pagination support

We recommend using Query API V1 for smaller extract queries. You can also use the API when you want to fetch a limited set of data by specifying offsets and limits.
  • Data Cloud licenses must be provisioned for your org
  • Users must have appropriate roles and permissions assigned
  • Authentication requires a valid access token
  • Connected App must be properly configured
  • No explicit limit exists for:
    • SQL call length
    • Number of nested queries
    • Number of joins
    • Number of filters
    • Number of column projections
    • Specific data types (VARCHAR, DECIMAL, TIMESTAMP, etc.)
  • Pagination is supported via cursor-based pagination:
    • The POST endpoint returns data along with nextBatchId for next batch
    • The GET endpoint is used for subsequent requests using the nextBatchId
    • Pagination is forward cursor only
    • You must fetch the complete result set within one hour
    • The time interval between batch calls must not exceed three minutes
    • When using aggregate functions, results are of number types instead of string types

  • POST /api/v2/query

    • Executes SQL queries against Data Cloud data
    • Returns query results with metadata and nextBatchId
    • Supports cursor-based pagination

  • GET /api/v2/query/{nextBatchId}

    • Returns the next batch of data from the initial POST request
    • Requires the nextBatchId from the previous response
    • Supports forward-only pagination
  • The API follows REST standards for consistency and usability
  • All API endpoints require proper authentication using an access token
  • Example URLs use {TSE} to represent your tenant-specific endpoint
  • Data access is subject to user permissions and role assignments
  • The query ID remains the same for both POST and GET calls