API Reference¶

You can find information here about all of Tinybird Analytics’s API endpoints, such as the Datasource API to import Data, the Pipe 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.

Check out the official javascript library if you want to access our API directly from your frontend applications.

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.

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 succesfull 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 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 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.

Response codes¶
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
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. Tinybird Analytics thottles 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. 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.

Limits¶
Description	Limit
SQL length	3kb
Result length	10Mb
Query Execution time	10s
Columns	2048
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.

Tinybirddocs