Query Execution

Run a query against a connected database service. Query Runner resolves credentials (user or team, layered on the service’s admin config), dispatches the query as a workflow, and streams results to object storage for retrieval.

Method	Endpoint	Description
`POST`	`/v1/collate/apps/queryRunner/trigger`	Execute a query.
`PUT`	`/v1/collate/apps/queryRunner/stop`	Cancel a running query.
`GET`	`/v1/collate/apps/queryRunner/results/{workflowId}`	Fetch a page of results by workflow ID.
`GET`	`/v1/collate/apps/queryRunner/health/storage`	Check that object storage for query results is reachable.

Trigger a Query

POST /v1/collate/apps/queryRunner/trigger accepts query, serviceName, workflowName, and transpile in the request body. Collate enriches the request server-side with the resolved user ID, config ID, connection type, auth type, and a maximum result size before dispatching it. Optional query parameters:

string

Run using a specific team’s credentials instead of the calling user’s own config.

boolean

default:"false"

Skip the user’s own credentials and use the team config even without an explicit teamId.

Stop a Query

PUT /v1/collate/apps/queryRunner/stop takes a body of { "workflowName": "..." } (required) and cancels the running workflow through the configured execution backend, marking it FAILED.

Fetch Results

GET /v1/collate/apps/queryRunner/results/{workflowId} returns a page of results by workflow ID. It’s paginated with page (default 0) and size (default 50, max 10000).

In Collate 2.0.2, this endpoint does not verify that the caller owns the workflow. Another authenticated caller who knows the workflow ID can retrieve its results. Treat workflow IDs as sensitive and avoid using this route for results that require owner-only access until authorization is enforced.

A companion POST /v1/collate/apps/queryRunner/results/{workflowId} endpoint exists for the execution worker to stream results into storage. It isn’t a client-facing endpoint.

Example

The following request starts a Query Runner workflow.

curl -X POST "{base_url}/api/v1/collate/apps/queryRunner/trigger" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM sales_orders LIMIT 100",
    "serviceName": "snowflake_production",
    "workflowName": "query-run-001"
  }'

curl "{base_url}/api/v1/collate/apps/queryRunner/results/{workflow_id}?page=0&size=50" \
  -H "Authorization: Bearer {access_token}"

​Query Execution

​Trigger a Query

​Stop a Query

​Fetch Results

​Example

Query Execution

Trigger a Query

Stop a Query

Fetch Results

Example