API Reference¶
All about of Tinybird Analytics’s API endpoints, such as the Datasource API to import Data, the Pipes API to transform data and publish the results through API endpoints, and the Query API to run arbitrary queries.
The API is organized around REST. All requests should be made over SSL. All response bodies, including errors, are encoded in JSON.
Authentication¶
Tinybird Analytics 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 Analytics API.
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:
curl -X GET \
"https://api.tinybird.co/v0/sql?q=SELECT+*+FROM+<pipe>&token=<token>"
Errors¶
Tinybird Analytics’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.
Code |
Description |
---|---|
200 |
No error |
400 |
Bad request. This could be due to a missing parameter in a request, for instance |
403 |
Forbidden. Provided Auth token doesn’t have the right scope or the datasource is not available |
404 |
Not found |
405 |
HTTP Method not allowed |
408 |
Request timeout (e.g. query execution time was exceeded) |
409 |
You 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) |
411 |
No valid Content-Length header containing the length of the message-body |
413 |
The message body is too large |
429 |
Too many requests. When over the rate limits of your account |
500 |
Unexpected error |
Limits¶
Tinybird Analytics APIs have rate limits that cap the number of requests that can be made against a specific endpoint. Your rate limit will depend on your pricing plan and the queries being executed.
The following limits apply to the Workspace Build plan. More details in the pricing page.
Description |
Limit and time window |
---|---|
API Endpoint and API SQL requests |
1,000 requests per day |
Data Sources storage |
10 gigabytes in total |
Tinybird Analytics 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.
Description |
Limit and time window |
---|---|
Create Data Source from schema |
25 times per minute |
Create Data Source from file or URL |
5 times per minute |
Append data to Data Source |
5 times per minute |
Append data to Data Source using v0/events |
1,000 times per second |
Replace data in a Data Source |
5 times per minute |
Please 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.
Header Name |
Description |
---|---|
|
The maximum number of requests you’re permitted to make in the current limit window. |
|
The number of requests remaining in the current rate limit window. |
|
The time in seconds after the current rate limit window resets. |
|
The time to wait before making a another request. Only present on 429 responses. |
Apart from the rate limits, Tinybird Analytics has other limits regarding the queries, the Data Sources, and the upload size.
Description |
Limit |
---|---|
SQL length |
8KB |
Result length |
10MB |
Query Execution time |
10s |
Data Source max columns |
2,048 |
Full body upload |
8MB |
Multipart upload |
10GB |
Max file size (uncompressed) |
32GB |
Versioning¶
All Tinybird Analytics 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.