> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcollate.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Query Execution

> Trigger a query, stop a running one, and fetch results through the Collate Query Runner API

# 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:

<ParamField query="teamId" type="string">
  Run using a specific team's credentials instead of the calling user's own config.
</ParamField>

<ParamField query="preferTeam" type="boolean" default="false">
  Skip the user's own credentials and use the team config even without an explicit `teamId`.
</ParamField>

## 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`).

<Warning>
  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.
</Warning>

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.

<RequestExample>
  ```bash Trigger a query theme={null}
  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"
    }'
  ```

  ```bash Fetch results theme={null}
  curl "{base_url}/api/v1/collate/apps/queryRunner/results/{workflow_id}?page=0&size=50" \
    -H "Authorization: Bearer {access_token}"
  ```
</RequestExample>