---
title: Endpoints
meta:
    description: Endpoints make it easy to use the results of your queries in applications.
---

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

{% tabs initial="Tinybird CLI" %}
{% tab label="Tinybird CLI" %}

```tb {% title="pipes/top_pages.pipe" %}
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
```

{% /tab %}

{% tab label="TypeScript SDK" %}

```ts {% title="tinybird.ts" %}
import { defineEndpoint, node, p, t } from "@tinybirdco/sdk";

export const topPages = defineEndpoint("top_pages", {
  description: "Get the most visited pages",
  params: {
    start_date: p.dateTime(),
    end_date: p.dateTime(),
    limit: p.int32().optional(10),
  },
  nodes: [
    node({
      name: "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)}}
      `,
    }),
  ],
  output: {
    pathname: t.string(),
    views: t.uint64(),
  },
});
```

{% /tab %}

{% tab label="Python SDK" %}

```python {% title="tinybird.py" %}
from tinybird_sdk import define_endpoint, node, p, t

top_pages = define_endpoint("top_pages", {
    "description": "Get the most visited pages",
    "params": {
        "start_date": p.date_time(),
        "end_date": p.date_time(),
        "limit": p.int32().optional(10),
    },
    "nodes": [
        node({
            "name": "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)}}
            """,
        }),
    ],
    "output": {
        "pathname": t.string(),
        "views": t.uint64(),
    },
})
```

{% /tab %}
{% /tabs %}

See all syntax options in the [Endpoint pipes reference](/forward/dev-reference/datafiles/pipe-files#endpoint-pipes), [TypeScript SDK reference](/forward/dev-reference/typescript-sdk-resources#endpoints), and [Python SDK reference](/forward/dev-reference/python-sdk-resources#endpoints).

You can list your endpoints and their URLs and tokens using the `tb endpoint` command. See [tb endpoint](/forward/dev-reference/commands/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:

```text
{% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/top_pages.json
{% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/top_pages.csv
{% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/top_pages.ndjson
{% user("apiHost", "https://api.tinybird.co") %}/v0/pipes/top_pages.parquet
{% user("apiHost", "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](/api-reference/pipe-api/api-endpoints#response-formats) 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](/forward/core-concepts/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](/forward/query-data/query-parameters).

## Errors and retries

For request behavior, HTTP error codes, and retry guidance, see [API Endpoints in Query Data](/forward/query-data/api-endpoints#errors-and-retries).