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

> Execute queries, manage connection configurations, and save queries through the Collate Query Runner REST API

# Query Runner

Query Runner executes SQL against your connected database services directly from Collate. The API is split across five resources: running and stopping queries, the admin-level connection configuration for a service, per-team and per-user credential overrides on top of that admin config, and saved queries.

<CardGroup cols={2}>
  <Card title="Execution" icon="play" href="/api-reference/query-runner/execution">
    Trigger a query, stop a running one, and fetch results.
  </Card>

  <Card title="Configs" icon="gear" href="/api-reference/query-runner/configs">
    The admin-level connection configuration for a service.
  </Card>

  <Card title="Saved Queries" icon="bookmark" href="/api-reference/query-runner/saved-queries">
    Save, list, update, and execute reusable queries.
  </Card>

  <Card title="Team Configs" icon="users" href="/api-reference/query-runner/team-configs">
    Team-level credential overrides on top of the admin config.
  </Card>

  <Card title="User Configs" icon="user" href="/api-reference/query-runner/user-configs">
    Per-user credential overrides, token refresh, and accessible role/database/schema lookups.
  </Card>
</CardGroup>

## Resource Model

| Concept | Base Path | Who manages it |
| - | - | - |
| Execution | `/v1/collate/apps/queryRunner` | Any user with query access |
| Admin Config | `/v1/queryRunner/configs` | Workspace admin, one config per service |
| Team Config | `/v1/queryRunner/team-configs` | Team owner or admin, one config per team per service |
| User Config | `/v1/queryRunner/user-configs` | Each user, one config per service |
| Saved Query | `/v1/queryRunner/savedQueries` | The owning user only |

A query normally uses the calling user's config for that service. If no user config exists, it falls back to an available connected team config. Setting `preferTeam=true` skips the user config and resolves a team config. Setting `teamId` selects a specific team. Both config types sit on top of an admin config that defines the service type and which fields users are allowed to override (`userConfigurableFields`, such as role, database, schema, warehouse, or dataset).

## Common Behavior

Authenticate every request with a bearer token. Admin, team, and user config secrets are masked in responses to ordinary users and must be resubmitted or explicitly preserved on update. Authorized bot callers can receive decrypted credentials, so avoid logging those responses. For setup details, see [Authentication](/api-reference/authentication).