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 Tinybird's pricing information here.

Build plan usage limits

DescriptionLimit and time window
API Endpoint1,000 requests per day
Data Sources storage10 gigabytes in total

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

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

Using the UI

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

First, create a Pipe in the UI.

On the Pipe view, 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).

Using the CLI

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

First, create a Pipe in the CLI.

Use the following command to publish an API Endpoint from the CLI. This automatically selects the final Node in the Pipe.

tb pipe publish PIPE_NAME_OR_ID

If you want to manually select a different Node to publish, supply the Node name as the final command argument:

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 also includes extra information about what went wrong, encoded in the response as JSON.

The HTTP error codes are:

Error codes

CodeDescription
400Bad 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.
403Forbidden. The Auth Token does not have the correct scopes.
404Not found. This usually occurs when the name of the API Endpoint is wrong or has not been published.
405HTTP Method not allowed. Requests to API Endpoints must use the GET method.
408Request timeout. This occurs when the query takes too long to complete by default this is 10 seconds.
429Too many requests. Usually occurs when an API Endpoint is hitting into rate limits.
500Internal 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 the Tokens API docs.

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.

Next steps