# Tinybird

> Work with your Tinybird workspace: add rows, import files, run SQL, call endpoints, run copy and sink pipes, follow jobs, sign read tokens and manage secrets, and start workflows on new rows, jobs and changed endpoint results.

App · 24 actions. Web page: https://docs.lodol.com/docs/integrations/tinybird

## Actions

### Add rows

Add one row, or a list of rows from an earlier step, to a data source, and wait until Tinybird has stored them. Fails, saying why, if a row doesn't match the data source's columns.

**Inputs**

- Data source (`data_source`, text, required): The data source. Pick one, or give its name.
- Row (`row`, object): A value for each column. Numbers and true or false are converted to the column's type.
- Rows (`rows`, list): A list of rows from an earlier step, each an object of column names and values. Added after the row above.

**Outputs**

- `data_source` (text): The data source the rows went to
- `quarantined_rows` (number): How many rows were set aside: always 0, since any fails the step
- `rows_added` (number): How many rows Tinybird stored
- `rows_sent` (number): How many rows were sent

**Example output**

```json
{
  "data_source": "events",
  "quarantined_rows": 0,
  "rows_added": 2,
  "rows_sent": 2
}
```

### Cancel copy jobs

Cancel a copy pipe's waiting and running jobs and pause its schedule. 'Resume copy schedule' starts it again.

**Inputs**

- Copy pipe (`pipe`, text, required): The copy pipe. Pick one, or give its name.

**Outputs**

- `cancelled_jobs` (true/false): False when no job was waiting or running
- `pipe` (text): The copy pipe
- `schedule_cron` (text): Its schedule, in cron format
- `schedule_status` (text): Whether the schedule is running or paused

**Example output**

```json
{
  "cancelled_jobs": true,
  "pipe": "copy_daily_totals",
  "schedule_cron": "0 * * * *",
  "schedule_status": "paused"
}
```

### Cancel job

Cancel a job that is still waiting (or a populate that is running). Rows it already wrote stay.

**Inputs**

- Job ID (`job_id`, text, required): The job's id, from a step that started it or 'List jobs'.

**Outputs**

- `job` (object): The job, now cancelling

**Example output**

```json
{
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "daily_totals",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": false,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "copy",
    "pipe": "copy_daily_totals",
    "row_count": null,
    "rows_affected": null,
    "started_at": "",
    "status": "cancelling",
    "updated_at": "2026-11-02 10:41:07.398128"
  }
}
```

### Create read token

Sign a token that may only read one endpoint (optionally with parameters fixed, such as one customer's id) or one data source, and stops working at the time given.

**Inputs**

- Token name (`name`, text, required): A name for the token, shown in Tinybird's logs.
- Reads (`resource_type`, text): What the token may read. Defaults to an endpoint. One of: `pipe` (An endpoint (pipe)), `data_source` (A data source).
- Endpoint (`pipe`, text): The endpoint the token may read. Only when Reads is An endpoint (pipe).
- Data source (`data_source`, text): The data source the token may read. Only when Reads is A data source.
- Fixed parameters (`fixed_params`, object): Parameter values the token always uses, which whoever holds it can't change, such as a customer's id. Only when Reads is An endpoint (pipe).
- Expires (`expires_at`, date and time, required): When the token stops working.

**Outputs**

- `expires_at` (number): When it expires, in Unix seconds
- `name` (text): The token's name
- `scope` (text): What it may read, such as PIPES:READ top_users
- `token` (text): The token, to send as a Bearer token or ?token=
- `url` (text): For an endpoint, an address that returns its rows (NDJSON) with the token; empty for a data source

**Example output**

```json
{
  "expires_at": 1793599082,
  "name": "customer_dashboard",
  "scope": "PIPES:READ top_users",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature",
  "url": "https://api.tinybird.co/v0/pipes/top_users.ndjson?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"
}
```

### Create secret

Store a value, such as a database password, that pipes read with tb_secret('name') without showing it.

**Inputs**

- Name (`name`, text, required): The secret's name: letters, digits and _, unique in the workspace.
- Value (`value`, text, required): The secret's value, at most 8 KB. Tinybird never shows it again.

**Outputs**

- `secret` (object): The secret

**Example output**

```json
{
  "secret": {
    "created_at": "2026-11-02T10:27:57",
    "edited_by": "token: 'workspace admin token'",
    "name": "pg_password",
    "type": "secret",
    "updated_at": "2026-11-02T10:29:57"
  }
}
```

### Delete rows

Delete the rows of a data source that match a SQL condition, as a job, or only count them first. Materialized views fed by it keep their rows.

**Inputs**

- Data source (`data_source`, text, required): The data source. Pick one, or give its name.
- Delete rows where (`condition`, text, required): A SQL condition on the data source's columns, such as country = 'ES' or timestamp < '2026-01-01'.
- Only count them (`dry_run`, true/false): Count the matching rows without deleting anything.

**Outputs**

- `data_source` (text): The data source
- `dry_run` (true/false): True when the rows were only counted
- `job` (object): The delete job
- `job_id` (text): The delete job's id, empty when only counted
- `rows_to_delete` (number): How many rows match, when only counted
- `status` (text): The delete job's status, empty when only counted

**Example output**

```json
{
  "data_source": "events",
  "dry_run": false,
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "events",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": true,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "delete_data",
    "pipe": "",
    "row_count": null,
    "rows_affected": null,
    "started_at": "",
    "status": "waiting",
    "updated_at": "2026-11-02 10:41:07.398128"
  },
  "job_id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
  "rows_to_delete": null,
  "status": "waiting"
}
```

### Delete secret

Delete a secret. Pipes that read it stop working.

**Inputs**

- Secret (`name`, text, required): The secret. Pick one, or give its name.

**Outputs**

- `deleted` (true/false): Always true once deleted
- `name` (text): The secret deleted

**Example output**

```json
{
  "deleted": true,
  "name": "pg_password"
}
```

### Empty data source

Remove every row from a data source, keeping the data source and its columns. This can't be undone.

**Inputs**

- Data source (`data_source`, text, required): The data source. Pick one, or give its name.

**Outputs**

- `data_source` (text): The data source emptied
- `emptied` (true/false): Always true once emptied

**Example output**

```json
{
  "data_source": "events",
  "emptied": true
}
```

### Get data source

Get one data source: its columns and their types, how many rows it holds, its engine and the pipes that read it.

**Inputs**

- Data source (`data_source`, text, required): The data source. Pick one, or give its name.

**Outputs**

- `data_source` (object): The data source

**Example output**

```json
{
  "data_source": {
    "bytes": 430833,
    "columns": [
      {
        "default_value": null,
        "name": "timestamp",
        "nullable": false,
        "type": "DateTime64(3)"
      },
      {
        "default_value": null,
        "name": "user_id",
        "nullable": false,
        "type": "String"
      },
      {
        "default_value": null,
        "name": "amount",
        "nullable": false,
        "type": "Float64"
      }
    ],
    "created_at": "2026-10-01 09:00:00.000000",
    "description": "Events from the web app.",
    "engine": "MergeTree",
    "format": "ndjson",
    "id": "t_bd1c62b5e67142bd9bf9a7f113a2b6ea",
    "name": "events",
    "row_count": 3980,
    "sorting_key": "timestamp, user_id",
    "updated_at": "2026-10-28 13:11:19.464343",
    "used_by": [
      "top_users"
    ]
  }
}
```

### Get endpoint results

Call a published endpoint with values for its parameters and return its rows.

**Inputs**

- Endpoint (`pipe`, text, required): The endpoint. Pick one, or give its name.
- Parameters (`parameters`, object): A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.

**Outputs**

- `bytes_read` (number): How many bytes were read
- `columns` (list): The columns, in order
- `elapsed_seconds` (number): How long it took, in seconds
- `pipe` (text): The endpoint called
- `row_count` (number): How many rows came back
- `rows` (list): The rows, one object per row
- `rows_before_limit` (number): At least how many rows matched before any LIMIT
- `rows_read` (number): How many rows were read

**Example output**

```json
{
  "bytes_read": 95520,
  "columns": [
    {
      "name": "user_id",
      "type": "String"
    },
    {
      "name": "total",
      "type": "Float64"
    }
  ],
  "elapsed_seconds": 0.0042,
  "pipe": "top_users",
  "row_count": 1,
  "rows": [
    {
      "total": 120.5,
      "user_id": "u_1842"
    }
  ],
  "rows_before_limit": 1,
  "rows_read": 3980
}
```

### Get job

Get one job's status, timings, rows and error, for 48 hours after it was created.

**Inputs**

- Job ID (`job_id`, text, required): The job's id, from a step that started it or 'List jobs'.

**Outputs**

- `job` (object): The job

**Example output**

```json
{
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "daily_totals",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": true,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "copy",
    "pipe": "copy_daily_totals",
    "row_count": 24,
    "rows_affected": null,
    "started_at": "",
    "status": "done",
    "updated_at": "2026-11-02 10:41:07.398128"
  }
}
```

### Get pipe

Get one pipe: what kind it is, the parameters it takes, its nodes' SQL and, for a copy or sink pipe, its schedule.

**Inputs**

- Pipe (`pipe`, text, required): The pipe. Pick one, or give its name.

**Outputs**

- `pipe` (object): The pipe

**Example output**

```json
{
  "pipe": {
    "created_at": "2026-10-01 09:10:00.000000",
    "description": "The users who spent most.",
    "id": "t_55c39255e6b548dd98cb6da4b7d62c1c",
    "name": "top_users",
    "nodes": [
      {
        "id": "t_h65c788b42ce4095a4789c0d6b0156c3",
        "name": "endpoint",
        "sql": "%\nSELECT user_id, sum(amount) AS total FROM events GROUP BY user_id ORDER BY total DESC LIMIT {{Int32(limit, 10)}}",
        "type": "endpoint"
      }
    ],
    "parameters": [
      {
        "default": 10,
        "description": "How many users",
        "name": "limit",
        "required": false,
        "type": "Int32"
      }
    ],
    "schedule_cron": "",
    "schedule_status": "",
    "type": "endpoint",
    "updated_at": "2026-10-28 13:33:40.850186",
    "url": "https://api.tinybird.co/v0/pipes/top_users.json"
  }
}
```

### Import file from URL

Have Tinybird load a CSV, NDJSON or Parquet file from a web address into a data source, adding its rows or replacing the data. Returns the import job; 'Get job' follows it.

**Inputs**

- Data source (`data_source`, text, required): The data source. Pick one, or give its name.
- File address (`url`, text, required): The file's web address, which Tinybird downloads.
- File format (`file_format`, text): The file's format. Defaults to CSV. One of: `csv` (CSV (default)), `ndjson` (NDJSON (one JSON object per line)), `parquet`.
- Existing rows (`mode`, text): Add the file's rows to what is there, or replace the data source's rows with them. Defaults to adding. One of: `append` (Add the file's rows (default)), `replace` (Replace the data with the file's rows).
- Replace only rows where (`replace_condition`, text): When replacing, a SQL condition such as date >= '2026-10-01': only matching rows are replaced. Leave empty to replace them all. Only when Existing rows is Replace the data with the file's rows.

**Outputs**

- `data_source` (text): The data source the file goes to
- `job` (object): The job
- `job_id` (text): The id of the job Tinybird started
- `status` (text): The job's status when it was started, usually waiting

**Example output**

```json
{
  "data_source": "events",
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "events",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": true,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "import",
    "pipe": "",
    "row_count": null,
    "rows_affected": null,
    "started_at": "",
    "status": "waiting",
    "updated_at": "2026-11-02 10:41:07.398128"
  },
  "job_id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
  "status": "waiting"
}
```

### List data sources

List the workspace's data sources (its tables) with their columns, size and the pipes that read them.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `data_sources` (list): The data sources

**Example output**

```json
{
  "count": 1,
  "data_sources": [
    {
      "bytes": 430833,
      "columns": [
        {
          "default_value": null,
          "name": "timestamp",
          "nullable": false,
          "type": "DateTime64(3)"
        },
        {
          "default_value": null,
          "name": "user_id",
          "nullable": false,
          "type": "String"
        },
        {
          "default_value": null,
          "name": "amount",
          "nullable": false,
          "type": "Float64"
        }
      ],
      "created_at": "2026-10-01 09:00:00.000000",
      "description": "Events from the web app.",
      "engine": "MergeTree",
      "format": "ndjson",
      "id": "t_bd1c62b5e67142bd9bf9a7f113a2b6ea",
      "name": "events",
      "row_count": 3980,
      "sorting_key": "timestamp, user_id",
      "updated_at": "2026-10-28 13:11:19.464343",
      "used_by": [
        "top_users"
      ]
    }
  ]
}
```

### List jobs

List the workspace's jobs (imports, copies, sinks, deletes) of the last 48 hours, at most 100, newest first.

**Inputs**

- Kind (`job_kind`, text): Only jobs of this kind. Leave empty for all. One of: `import`, `copy` (Copy pipe), `sink` (Sink pipe), `populateview` (Materialized view populate), `delete_data` (Delete rows), `deployment`.
- Status (`status`, text): Only jobs in this status. Leave empty for all. One of: `waiting`, `working`, `done`, `error` (Failed), `cancelling`, `cancelled`.
- Pipe (`pipe`, text): Only jobs of this pipe. Leave empty for all.
- Created after (`created_after`, date and time): Only jobs created after this time.
- Created before (`created_before`, date and time): Only jobs created before this time.

**Outputs**

- `count` (number): How many
- `jobs` (list): The jobs

**Example output**

```json
{
  "count": 1,
  "jobs": [
    {
      "created_at": "2026-11-02 10:41:07.398102",
      "data_source": "daily_totals",
      "error": "",
      "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
      "is_cancellable": true,
      "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
      "kind": "copy",
      "pipe": "copy_daily_totals",
      "row_count": null,
      "rows_affected": null,
      "started_at": "",
      "status": "done",
      "updated_at": "2026-11-02 10:41:07.398128"
    }
  ]
}
```

### List pipes

List the workspace's pipes (its endpoints, copy, sink and other pipes) with the parameters each takes.

**Inputs**

- Kind (`pipe_type`, text): Only pipes of this kind. Leave empty for all. One of: `endpoint`, `copy`, `sink`, `materialized` (Materialized view), `default` (Plain pipe).

**Outputs**

- `count` (number): How many
- `pipes` (list): The pipes

**Example output**

```json
{
  "count": 1,
  "pipes": [
    {
      "created_at": "2026-10-01 09:10:00.000000",
      "description": "The users who spent most.",
      "id": "t_55c39255e6b548dd98cb6da4b7d62c1c",
      "name": "top_users",
      "nodes": [
        {
          "id": "t_h65c788b42ce4095a4789c0d6b0156c3",
          "name": "endpoint",
          "sql": "%\nSELECT user_id, sum(amount) AS total FROM events GROUP BY user_id ORDER BY total DESC LIMIT {{Int32(limit, 10)}}",
          "type": "endpoint"
        }
      ],
      "parameters": [
        {
          "default": 10,
          "description": "How many users",
          "name": "limit",
          "required": false,
          "type": "Int32"
        }
      ],
      "schedule_cron": "",
      "schedule_status": "",
      "type": "endpoint",
      "updated_at": "2026-10-28 13:33:40.850186",
      "url": "https://api.tinybird.co/v0/pipes/top_users.json"
    }
  ]
}
```

### List secrets

List the workspace's secrets (the values pipes read with tb_secret) by name. Tinybird never returns their values.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `secrets` (list): The secrets

**Example output**

```json
{
  "count": 1,
  "secrets": [
    {
      "created_at": "2026-11-02T10:27:57",
      "edited_by": "token: 'workspace admin token'",
      "name": "pg_password",
      "type": "secret",
      "updated_at": "2026-11-02T10:29:57"
    }
  ]
}
```

### List tokens

List the workspace's tokens by name with what each may do. The tokens themselves are left out.

**Inputs**: None.

**Outputs**

- `count` (number): How many
- `tokens` (list): The tokens

**Example output**

```json
{
  "count": 1,
  "tokens": [
    {
      "description": "",
      "id": "017a167c-5b1b-46b5-8791-897e87c4d293",
      "name": "workspace admin token",
      "scopes": [
        "ADMIN"
      ]
    }
  ]
}
```

### Pause copy schedule

Stop a scheduled copy pipe from starting new runs. A run already copying finishes.

**Inputs**

- Copy pipe (`pipe`, text, required): The copy pipe. Pick one, or give its name.

**Outputs**

- `pipe` (text): The copy pipe
- `schedule_cron` (text): Its schedule, in cron format
- `schedule_status` (text): Whether the schedule is running or paused

**Example output**

```json
{
  "pipe": "copy_daily_totals",
  "schedule_cron": "0 * * * *",
  "schedule_status": "paused"
}
```

### Resume copy schedule

Let a paused copy pipe's schedule start runs again.

**Inputs**

- Copy pipe (`pipe`, text, required): The copy pipe. Pick one, or give its name.

**Outputs**

- `pipe` (text): The copy pipe
- `schedule_cron` (text): Its schedule, in cron format
- `schedule_status` (text): Whether the schedule is running or paused

**Example output**

```json
{
  "pipe": "copy_daily_totals",
  "schedule_cron": "0 * * * *",
  "schedule_status": "running"
}
```

### Run copy pipe

Run a copy pipe now, writing its result into its target data source. Returns the copy job; 'Get job' follows it.

**Inputs**

- Copy pipe (`pipe`, text, required): The copy pipe. Pick one, or give its name.
- Parameters (`parameters`, object): A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.
- Target's rows (`mode`, text): Add the result to the target data source, or replace its rows with it. Defaults to the pipe's own setting. One of: `append` (Add to the target's rows (default)), `replace` (Replace the target's rows).

**Outputs**

- `job` (object): The job
- `job_id` (text): The id of the job Tinybird started
- `pipe` (text): The copy pipe
- `status` (text): The job's status when it was started, usually waiting

**Example output**

```json
{
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "daily_totals",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": true,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "copy",
    "pipe": "copy_daily_totals",
    "row_count": null,
    "rows_affected": null,
    "started_at": "",
    "status": "waiting",
    "updated_at": "2026-11-02 10:41:07.398128"
  },
  "job_id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
  "pipe": "copy_daily_totals",
  "status": "waiting"
}
```

### Run sink pipe

Run a sink pipe now, exporting its result to its bucket or Kafka topic. Returns the sink job; 'Get job' follows it.

**Inputs**

- Sink pipe (`pipe`, text, required): The sink pipe. Pick one, or give its name.
- Parameters (`parameters`, object): A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.
- File name (`file_template`, text): A file name for this run instead of the pipe's own, such as daily_export_{date}.
- File format (`file_format`, text): A format for this run instead of the pipe's own. One of: `csv`, `ndjson`, `parquet`.
- Compression (`compression`, text): Compress the files for this run. One of: `none`, `gz` (Gzip).
- When the file exists (`write_strategy`, text): What to do when a file of that name is already there. One of: `new` (Add a new file beside an existing one), `truncate` (Replace an existing file).

**Outputs**

- `job` (object): The job
- `job_id` (text): The id of the job Tinybird started
- `pipe` (text): The sink pipe
- `status` (text): The job's status when it was started, usually waiting

**Example output**

```json
{
  "job": {
    "created_at": "2026-11-02 10:41:07.398102",
    "data_source": "",
    "error": "",
    "id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "is_cancellable": true,
    "job_url": "https://api.tinybird.co/v0/jobs/c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
    "kind": "sink",
    "pipe": "export_daily",
    "row_count": null,
    "rows_affected": null,
    "started_at": "",
    "status": "waiting",
    "updated_at": "2026-11-02 10:41:07.398128"
  },
  "job_id": "c8ae13ef-e739-40b6-8bd5-b1e07c8671c2",
  "pipe": "export_daily",
  "status": "waiting"
}
```

### Run SQL query

Run a SQL SELECT over the workspace's data sources and pipes and return the rows. Values can be passed as parameters and read in the query with {{String(name)}}.

**Inputs**

- SQL (`sql`, text, required): The SELECT to run, without a FORMAT clause. A pipe's name reads it like a table.
- Parameters (`parameters`, object): Values the query reads by name, such as user_id read with {{String(user_id)}}.

**Outputs**

- `bytes_read` (number): How many bytes were read
- `columns` (list): The columns, in order
- `elapsed_seconds` (number): How long it took, in seconds
- `row_count` (number): How many rows came back
- `rows` (list): The rows, one object per row
- `rows_before_limit` (number): At least how many rows matched before any LIMIT
- `rows_read` (number): How many rows were read

**Example output**

```json
{
  "bytes_read": 95520,
  "columns": [
    {
      "name": "user_id",
      "type": "String"
    },
    {
      "name": "total",
      "type": "Float64"
    }
  ],
  "elapsed_seconds": 0.0042,
  "row_count": 1,
  "rows": [
    {
      "total": 120.5,
      "user_id": "u_1842"
    }
  ],
  "rows_before_limit": 1,
  "rows_read": 3980
}
```

### Update secret

Give an existing secret a new value.

**Inputs**

- Secret (`name`, text, required): The secret. Pick one, or give its name.
- Value (`value`, text, required): The secret's value, at most 8 KB. Tinybird never shows it again.

**Outputs**

- `secret` (object): The secret

**Example output**

```json
{
  "secret": {
    "created_at": "2026-11-02T10:27:57",
    "edited_by": "token: 'workspace admin token'",
    "name": "pg_password",
    "type": "secret",
    "updated_at": "2026-11-02T10:29:57"
  }
}
```
