Execute Custom SQL Query

Run custom SQL queries for structured data retrieval. The response returns the query results in a JSON format.

📘

Running your Query in SQL Builder

If you wish to run your query using the SQL Builder interface rather than via API (e.g. for testing or data exploration), replace @startDate and @endDate (camelCase) with @start_date and @end_date (snake_case) in the SQL expression.

📘

Matching Dashboard Results

Matching SQL text alone does not guarantee that an API request returns the same results as a dashboard. A dashboard can apply saved settings that are not included when you copy its SQL, such as the attribution model, the attribution window, and whether purchases are reported by click date or purchase date.

To compare results, match those settings along with the dates and filters. For queries on the Pixel Joined table, these settings correspond to model, attribution_window, and use_click_date. If a query does not set them, Pixel Joined uses the Triple Attribution model, the Lifetime attribution window, and the purchase date.

If results still differ, contact Triple Whale Support with the SQL query, the dashboard settings, the API request with API keys and other credentials removed, and both results.

🚧

Best Practices

Select Specific Columns

Avoid using SELECT * in your queries. Our schema is dynamic, and using wildcard selection can lead to broken or inconsistent results as fields change. Always specify the exact columns you need.

Rate Limits

The API enforces two rate limits:

  • 100 requests per second
  • 600 requests per minute

If you exceed these quotas, the API will return a 429 Too Many Requests error.

🤔

Compare with Data Warehouse Export

Use Data Warehouse Export instead if you want to push data directly to BigQuery, Snowflake, AWS S3, or GCS.

Body Params
string
required

The unique identifier for the shop (e.g., example.myshopify.com). This is the shop-id value in your Triple Whale app URL (for example ?shop-id=example.myshopify.com).

string
required

The SQL query string to execute. Include dynamic @startDate AND @endDate parameters in your query string, and provide specific start and end values in the request body via period.startDate and period.endDate.

string

The currency for data aggregation (e.g., USD, EUR). Defaults to the currency provided during user account registration.

period
object
required

The date range for the query period.

Responses

Language
Credentials
Header
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json