API Overview

You can control Tinybird services using the API. This is an alternative way to interact with Tinybird, along with the UI and CLI.

There are several APIs available to interact with Tinybird services:

Requests to Tinybird's API Endpoints must be made over TLS (HTTPS). All response bodies, including errors, are encoded in JSON.

Regions and endpoints

A Workspace belongs to one region. The API for each region has a specific API base URL that you will use to make API requests.

The following table lists the current regions and their corresponding API base URLs:

Current Tinybird regions

RegionProviderProvider regionAPI base URL
EuropeGCPeurope-west3https://api.tinybird.co
US EastGCPus-east4https://api.us-east.tinybird.co
EuropeAWSeu-central-1https://api.eu-central-1.aws.tinybird.co
US EastAWSus-east-1https://api.us-east.aws.tinybird.co

Tinybird documentation will typically use https://api.tinybird.co as the API base URL. If you are not using the Europe GCP region, you will need to replace this with the API base URL for your region.

Authentication

Tinybird makes use of Auth tokens for every API call. This ensures that each user/application can only access data that they are authorized to access. Learn more about Auth Tokens.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

There are two ways two authenticate your requests in the Tinybird API.

1. Authorization header

You can send a "Bearer authorization" header. With curl this would look like -H "Authorization: Bearer <token>".

If you have a valid token with read access to the particular Datasource, you should be able to get a successful response by sending the following request.

Authorization header Authenticated request
curl \
-X GET \
-H "Authorization: Bearer <token>" \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>"

2. URL parameter

You can also specify the token via a parameter in the URL, using token=<token>.

The following request is equivalent to the previous one:

URL parameter authenticated request
curl -X GET \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>&token=<token>"

Errors

Tinybird's API returns standard HTTP success or error status codes. For errors, we will also include extra information about what went wrong encoded in the response as JSON. The various HTTP status codes we might return are listed below.

Response codes

Code Description
200No error
400Bad request. This could be due to a missing parameter in a request, for instance
403Forbidden. Provided Auth token doesn't have the right scope or the datasource is not available
404Not found
405HTTP Method not allowed
408Request timeout (e.g. query execution time was exceeded)
409You need to resubmit the request due to a conflict with the current state of the target source (e.g.: you need to delete a materialized view)
411No valid Content-Length header containing the length of the message-body
413The message body is too large
429Too many requests. When over the rate limits of your account
500Unexpected error

Limits

Tinybird throttles requests based on the capacity. So if your queries are using 100% resources you might not be able to run more queries until the running ones finish.

Default rate limits

DescriptionLimit and time window
Create Data Source from schema25 times per minute
Create Data Source from file or URL5 times per minute
Append data to Data Source5 times per minute
Append data to Data Source using v0/events1,000 times per second
Replace data in a Data Source5 times per minute

Note that the quota for "Create Data Source from file or URL", "Append to Data Source", and "Replace data in Data Source" is shared. That is, you cannot do 5 requests of each type per minute, for a total of 15 requests. You can do at most a grand total of 5 requests of those types combined.

If you exceed your rate limit, your request will be throttled and you will receive HTTP 429 Too Many Requests response codes from the API. Each response contains a set of HTTP headers with your current rate limit status.

Rate limit headers

Header NameDescription
X-RateLimit-LimitThe maximum number of requests you're permitted to make in the current limit window.
X-RateLimit-RemainingThe number of requests remaining in the current rate limit window.
X-RateLimit-ResetThe time in seconds after the current rate limit window resets.
Retry-AfterThe time to wait before making a another request. Only present on 429 responses.

Apart from the rate limits, Tinybird has other limits regarding the queries, the Data Sources, and the upload size.

Default general limits

Description Limit
SQL length8KB
Result length100MB
Query Execution time10s
Data Source max columns2,048
Full body upload8MB
Multipart upload - CSV and NDJSON500MB
Multipart upload - Parquet50MB
Max file size - Parquet1GB
Max file size (uncompressed) free plan10GB
Max file size (uncompressed) pro and enterprise32GB
Max request size - Events API10MB

Versioning

All Tinybird APIs are versioned with a version string specified in the base URL. We encourage you to always use the latest API available.

When versioning our web services, we follow semantic versioning rules. Given a version number MAJOR.MINOR.PATCH, we increment the:

  • MAJOR version when you make incompatible API changes,
  • MINOR version when you add functionality in a backwards-compatible manner, and
  • PATCH version when you make backwards-compatible bug fixes.

Forbidden names

Words below are considered as reserved words and cannot be used to name Data Sources, Pipes, Nodes or Workspaces. Case of the words is ignored.

Array, Boolean, Date, Date32, DateTime, DateTime32, DateTime64, Decimal, Decimal128, Decimal256, Decimal32, Decimal64, Enum, Enum16, Enum8, FixedString, Float32, Float64, IPv4, IPv6, Int128, Int16, Int256, Int32, Int64, Int8, MultiPolygon, Point, Polygon, Ring, String, TABLE, UInt128, UInt16, UInt256, UInt32, UInt64, UInt8, UUID, _temporary_and_external_tables, add, after, all, and, anti, any, array, as, asc, asof, between, by, case, collate, column, columns, cross, cube, custom_error, day_diff, default, defined, desc, distinct, else, end, enumerate_with_last, error, exists, from, full, functions, generateRandom, global, group, having, if, ilike, in, inner, insert, interval, into, join, left, like, limit, limits, max, min, not, null, numbers_mt, on, one, or, order, outer, prewhere, public, right, sample, select, semi, split_to_array, sql_and, sql_unescape, system, table, then, tinybird, to, union, using, where, with, zeros_mt

Pipe, Data Source and Node names are globally unique. You cannot use an alias for a column that matches a globally unique name.