View all methods

studio.queryRuns.execute

Start a Data Studio query run. This method validates the SQL, creates a query run, and queues execution asynchronously.

Facts
Method POST https://api.getdx.com/studio.queryRuns.execute
Required scope datacloud:query

Arguments

Required arguments

Name Type Description
token Token Auth token passed as an HTTP header.
sql Text A single read-only SELECT statement to execute.

Optional arguments

Name Type Description
variables Object Key/value map for Data Studio template variables referenced in the SQL. Use variable names without the leading $. Values may be scalars or arrays.

Usage info

  • Returns 202 Accepted when the query run is created successfully.
  • The response includes a stable query run id plus info_url and results_url for follow-up requests.
  • Queued responses include a Retry-After: 1 header.
  • The HTTP response also includes a Location header pointing to studio.queryRuns.info.

Example request

This is a typical request:

curl -X POST https://api.getdx.com/studio.queryRuns.execute \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer xxxx-xxxxxxxxx-xxxx' \
  -H 'Content-Type: application/json' \
  --data '{
    "sql": "SELECT id, name FROM github_repos WHERE id IN ($repo_ids) LIMIT 10",
    "variables": {
      "repo_ids": ["1", "2", "3"]
    }
  }'

Example response

This is a typical success response:

{
  "ok": true,
  "query_run": {
    "id": "r3jv7p0x4gk2",
    "status": "queued",
    "submitted_at": "2026-04-13T20:10:05Z",
    "finished_at": null,
    "expires_at": "2026-05-13T20:10:05Z",
    "info_url": "/studio.queryRuns.info?id=r3jv7p0x4gk2",
    "results_url": "/studio.queryRuns.results?id=r3jv7p0x4gk2"
  }
}

Errors

This table lists the expected errors that this method could return. However, other errors can be returned in the case where the service is down or other unexpected factors affect processing. Callers should always check the value of the ok param in the response.

Error Description
not_authed No authentication token provided.
invalid_auth Some aspect of authentication cannot be validated.
not_authorized The API token does not include the required datacloud:query scope.
empty_sql The SQL query is blank.
invalid_sql The SQL query could not be parsed.
multiple_statements More than one SQL statement was provided.
non_read_only_sql The SQL is not a read-only SELECT query.
unsupported_query_reference Studio query references such as $query_... are not supported.
invalid_variables The variables argument must be an object.
query_run_user_not_available No active datacloud-capable user is available to own the query run.
ore.search.term">"