---
title: Query API
meta:
  description: Run SQL queries against Tinybird over HTTP.
---

# Query API

The [Query API](/api-reference/query-api) runs SQL directly against Pipes and Data Sources in your Workspace through the `/v0/sql` endpoint. Use it for internal tools, automation, and ad hoc queries that do not need a published Endpoint contract.

Use API Endpoints for production query contracts that applications call repeatedly. Use the Query API when the SQL is owned by the caller, such as an internal tool, notebook, script, or debugging workflow.

Query API requests can also use typed [Query parameters](/forward/query-data/query-parameters) when you need validated request-time values.

## Run a SQL query

Send a request to `/v0/sql` with a `q` parameter containing the SQL query. Use a Token with read permissions for the resources you query. Use a [static Token](/forward/core-concepts/static-tokens) for backend services and trusted internal tools. Use a [JWT](/forward/core-concepts/jwt) for browser, user-facing, or multi-tenant access where each user or tenant needs scoped access, filters, expiration, or rate limits.

For short queries, use `GET` and pass the SQL in the `q` query parameter:

```shell
curl \
  -H "Authorization: Bearer <read token or JWT>" \
  --get \
  --data-urlencode "q=SELECT * FROM <pipe_or_datasource> FORMAT JSON" \
  {% user("apiHost", "https://api.tinybird.co") %}/v0/sql
```

Use `POST` when the SQL query or request parameters are large. This avoids URL length limits and keeps long queries out of the URL:

```shell
curl \
  -X POST \
  -H "Authorization: Bearer <read token or JWT>" \
  --data-urlencode "q=SELECT * FROM <pipe_or_datasource> FORMAT JSON" \
  {% user("apiHost", "https://api.tinybird.co") %}/v0/sql
```

You can query Data Sources and Pipes by name. Add a `FORMAT` clause when you need a specific response format.

## Available response formats

Set the response format with a ClickHouse `FORMAT` clause at the end of the SQL query:

```sql
SELECT * FROM events LIMIT 10 FORMAT JSON
```

Common formats include:

{% table %}
* Format
* Use when
---
* `JSON`
* You need the default JSON response with metadata.
---
* `CSV`
* You need comma-separated values without headers.
---
* `CSVWithNames`
* You need comma-separated values with column headers.
---
* `JSONEachRow`
* You need newline-delimited JSON.
---
* `Parquet`
* You need a binary columnar format for larger exports or downstream analytics tools.
{% /table %}

If you don't specify a `FORMAT`, Tinybird returns the default Query API format. For the full endpoint contract, see the [Query API reference](/api-reference/query-api).

## Use query parameters

Query API requests can use Tinybird's [templating language](/forward/core-concepts/templating-language) and receive request parameters the same way API Endpoints do. This is useful when an internal tool or script owns the SQL but still needs typed, validated inputs.

```shell
curl \
  -X POST \
  -H "Authorization: Bearer <read token or JWT>" \
  --data-urlencode "q=% SELECT count() FROM events WHERE timestamp >= {{DateTime(start_date)}} FORMAT JSON" \
  --data-urlencode "start_date=2026-01-01 00:00:00" \
  {% user("apiHost", "https://api.tinybird.co") %}/v0/sql
```

For parameter syntax, defaults, and helper functions, see [Templating language](/forward/core-concepts/templating-language) and [Query parameters](/forward/query-data/query-parameters).

## Query a specific Pipe

You can also run a SQL query against a specific Pipe. Send the request to `/v0/pipes/<pipe>.json` and use `_` as the Pipe input in the `q` parameter:

```shell
curl \
  -X POST \
  -H "Authorization: Bearer <read token or JWT>" \
  --data "q=SELECT count() FROM _" \
  {% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/<pipe>.json
```

This is useful when you want to reuse a Pipe's logic but apply an extra aggregation, filter, or format at request time.

## Track Query API usage

Query API requests are logged as `query_api` in Service Data Sources. Add metadata as request parameters when you want to group requests by application, customer, or workflow.

```shell
curl \
  -X POST \
  -H "Authorization: Bearer <read token or JWT>" \
  --data "q=SELECT count() FROM events FORMAT JSON" \
  "{% user("apiHost", "https://api.tinybird.co") %}/v0/sql?app_name=internal_tool"
```

See [Endpoint performance](/forward/monitoring/analyze-endpoints-performance#use-the-query-api-with-metadata-parameters) for monitoring examples.

## Next steps

- Review the [Query API reference](/api-reference/query-api).
- Add typed parameters with [Query parameters](/forward/query-data/query-parameters).
- Use the [ClickHouse interface](/forward/query-data/clickhouse-interface) for SQL clients and BI tools.