API Endpoints¶

Endpoints are a type of pipe that you can call from other applications. You ingest your data into your Data Sources, build SQL logic inside a pipe, and then publish the result of your query as a REST API endpoint.

Create an endpoint¶

You define Endpoints in .pipe files with the TYPE ENDPOINT directive, with defineEndpoint in the TypeScript SDK, or with define_endpoint in the Python SDK.

DESCRIPTION >
    Get the most visited pages

TOKEN dashboard READ

NODE aggregated
SQL >
    %
    SELECT pathname, count() AS views
    FROM page_views
    WHERE timestamp >= {{DateTime(start_date)}}
      AND timestamp <= {{DateTime(end_date)}}
    GROUP BY pathname
    ORDER BY views DESC
    LIMIT {{Int32(limit, 10)}}

TYPE ENDPOINT

See all syntax options in the Endpoint pipes reference, TypeScript SDK reference, and Python SDK reference.

You can list your endpoints and their URLs and tokens using the tb endpoint command. See tb endpoint.

Response formats¶

API Endpoints can return results in different formats. Choose the response format by appending the format extension to the Endpoint URL.

For example:

https://api.tinybird.co/v0/pipes/top_pages.json
https://api.tinybird.co/v0/pipes/top_pages.csv
https://api.tinybird.co/v0/pipes/top_pages.ndjson
https://api.tinybird.co/v0/pipes/top_pages.parquet
https://api.tinybird.co/v0/pipes/top_pages.prometheus

Supported formats include:

• .json: JSON response. This is the default format.
• .csv: CSV response.
• .csvwithnames: CSV response with column names.
• .ndjson: Newline-delimited JSON response.
• .parquet: Parquet response.
• .prometheus: Prometheus metrics response. Use this when you want observability tools to scrape an Endpoint.

See the Pipe API reference for request parameters and response details.

Query parameters¶

API Endpoints can receive query parameters to make the published query dynamic at request time. Use parameters for filters, date ranges, pagination, sorting, tenant IDs, and limits.

API Endpoints use Tinybird's templating language to validate parameter types and render SQL safely before the query runs.

For parameter syntax, defaults, helper functions, pagination, and advanced patterns, see Query parameters.

Errors and retries¶

For request behavior, HTTP error codes, and retry guidance, see API Endpoints in Query Data.