API Endpoints

What is an API Endpoint?

Tinybird enables you to publish the result of any query as an HTTP API.

Write your SQL query, click a button, and get a scalable, reliable & secure API with no effort.

What should I use API Endpoints for?

API Endpoints make it easy to use the results of your queries in applications. Any app that can run an HTTP GET can use Tinybird API Endpoints.

Build plan limits

The Build plan is Tinybird’s free-tier. This plan has a limit on the amount of API requests per day that can be made against published API Endpoints.

You can find pricing information here.

Build plan usage limits

Description	Limit and time window
API Endpoint	1,000 requests per day
Data Sources storage	10 gigabytes in total

These limits do not apply to Tinybird’s paid plans.

Creating API Endpoints

To create an API Endpoint in Tinybird, you first need to create a Pipe. You can publish any of the queries in your Pipes as an API Endpoint.

Creating API Endpoints in the UI

This section describes how to create an API Endpoint in the UI.

Need helping creating a Pipe in the UI? Here’s how!

Open the Pipe that you want to publish and click the Create API Endpoint button in the top right of the sceen (see Mark 1 below). Then select the Node that you want to publish (see Mark 2 below).

Creating API Endpoints in the CLI

This section describes how to create an API Endpoint in the CLI.

Need helping creating a Pipe in the CLI? Here’s how!

Use the command below to publish an API Endpoint from the CLI. This will automatically select the final Node in the Pipe.

tb pipe publish PIPE_NAME_OR_ID

If you want to manually select which Node is published, supply the Node name as the final command argument, as below.

tb pipe publish PIPE_NAME_OR_ID NODE_NAME

Errors and retries

Error codes

API Endpoints return standard HTTP success or error codes. For errors, the response will also include extra information about what went wrong, encoded in the response as JSON.

The various HTTP error codes are:

Error codes

Code	Description
400	Bad request. A HTTP400 can be returned in several scenarios, and typically represents a malformed request, such as errors in your SQL queries or missing query parameters.
403	Forbidden. The Auth Token does not have the correct scopes.
404	Not found. This usually occurs when the name of the API Endpoint is wrong, or has not been published.
405	HTTP Method not allowed. Requests to API Endpoints must use the GET method.
408	Request timeout. This occurs when the query takes too long to complete, by default this is 10 seconds.
429	Too many requests. Usually occurs when an API Endpoint is hitting into rate limits.
500	Internal Server Error. Usually an unexpected, transient service error.

When to retry

In most cases, a HTTP4xx error should not be automatically retried. These errors are unlikely to be resolved by simply retrying the same request, and will require modifications to the request or underlying query.

There are two error codes where automatic retries should be implemented:

• HTTP429: Too many requests

• HTTP500: Internal Server Error

How to retry

In general, you should retry a request 3-5 times. If the failure persists beyond these retries, you should gracefully handle the failure and log the occurance for investigation.

It is recommended to use an exponential backoff between retries. This means that, after a retry fails, you should increase the amount of time you wait before sending the next retry. If the issue causing the failure is transient, this gives you a better chance of a successful retry. You should be careful when calculating backoff timings, so that you do not run into memory limits on your application.

FAQs

How is data security handled?

In order to read, append or import data, you’ll need an Auth Token with the right permissions. You can define tokens with any scope, and even make it granular enough to handle row-level security (e.g. client 123 can only see data where “client_id = 123”). Read more about Auth Tokens in this guide.

Do Auth Tokens expire?

Auth Tokens do not expire. You have the ability to refresh a token; any application using that token will need to be updated.

Can Tinybird API Endpoints push data?

No, you must make a request to the API Endpoint to query data.

Should I use the Query API or API Endpoints in my application?

The Query API is similar to running SQL statements against a normal database instead of using it as your backend. It can be useful for ad-hoc queries, but it’s not a fully productized API like the API Endpoints.

We recommend building pipes and publishing Endpoints for several reasons:

• You can build and maintain all of your logic in Tinybird, and simply call the Endpoint to get the result. With the Query API, you must write a full SELECT statement in your code.

• You can use incremental nodes in your Pipes to simplify the development and maintenance of your queries. With the Query API, you could end up writing a complex nested query.

• Endpoints support query parameters and more complex logic with the Tinybird templating language.

• Endpoints automatically incorporate any changes from your query, which means little downstream impact.