Tinybird

App · 24 actions

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.

Actions

ActionWhat it does
Add rowsAdd one row, or a list of rows from an earlier step, to a data source, and wait until Tinybird has stored them.
Cancel copy jobsCancel a copy pipe's waiting and running jobs and pause its schedule.
Cancel jobCancel a job that is still waiting (or a populate that is running).
Create read tokenSign 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.
Create secretStore a value, such as a database password, that pipes read with tb_secret('name') without showing it.
Delete rowsDelete the rows of a data source that match a SQL condition, as a job, or only count them first.
Delete secretDelete a secret.
Empty data sourceRemove every row from a data source, keeping the data source and its columns.
Get data sourceGet one data source: its columns and their types, how many rows it holds, its engine and the pipes that read it.
Get endpoint resultsCall a published endpoint with values for its parameters and return its rows.
Get jobGet one job's status, timings, rows and error, for 48 hours after it was created.
Get pipeGet one pipe: what kind it is, the parameters it takes, its nodes' SQL and, for a copy or sink pipe, its schedule.
Import file from URLHave Tinybird load a CSV, NDJSON or Parquet file from a web address into a data source, adding its rows or replacing the data.
List data sourcesList the workspace's data sources (its tables) with their columns, size and the pipes that read them.
List jobsList the workspace's jobs (imports, copies, sinks, deletes) of the last 48 hours, at most 100, newest first.
List pipesList the workspace's pipes (its endpoints, copy, sink and other pipes) with the parameters each takes.
List secretsList the workspace's secrets (the values pipes read with tb_secret) by name.
List tokensList the workspace's tokens by name with what each may do.
Pause copy scheduleStop a scheduled copy pipe from starting new runs.
Resume copy scheduleLet a paused copy pipe's schedule start runs again.
Run copy pipeRun a copy pipe now, writing its result into its target data source.
Run sink pipeRun a sink pipe now, exporting its result to its bucket or Kafka topic.
Run SQL queryRun a SQL SELECT over the workspace's data sources and pipes and return the rows.
Update secretGive an existing secret a new value.

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 sourcedata_sourcetextRequired
The data source. Pick one, or give its name.
Rowrowobject
A value for each column. Numbers and true or false are converted to the column's type.
Rowsrowslist
A list of rows from an earlier step, each an object of column names and values. Added after the row above.

Outputs

data_sourcetext
The data source the rows went to
quarantined_rowsnumber
How many rows were set aside: always 0, since any fails the step
rows_addednumber
How many rows Tinybird stored
rows_sentnumber
How many rows were sent
Example output
{
  "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 pipepipetextRequired
The copy pipe. Pick one, or give its name.

Outputs

cancelled_jobstrue/false
False when no job was waiting or running
pipetext
The copy pipe
schedule_crontext
Its schedule, in cron format
schedule_statustext
Whether the schedule is running or paused
Example output
{
  "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 IDjob_idtextRequired
The job's id, from a step that started it or 'List jobs'.

Outputs

jobobject
The job, now cancelling
Example output
{
  "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 namenametextRequired
A name for the token, shown in Tinybird's logs.
Readsresource_typetext
What the token may read. Defaults to an endpoint.One of: pipe (An endpoint (pipe)), data_source (A data source).
Endpointpipetext
The endpoint the token may read.Only when Reads is An endpoint (pipe).
Data sourcedata_sourcetext
The data source the token may read.Only when Reads is A data source.
Fixed parametersfixed_paramsobject
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).
Expiresexpires_atdate and timeRequired
When the token stops working.

Outputs

expires_atnumber
When it expires, in Unix seconds
nametext
The token's name
scopetext
What it may read, such as PIPES:READ top_users
tokentext
The token, to send as a Bearer token or ?token=
urltext
For an endpoint, an address that returns its rows (NDJSON) with the token; empty for a data source
Example output
{
  "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

NamenametextRequired
The secret's name: letters, digits and _, unique in the workspace.
ValuevaluetextRequired
The secret's value, at most 8 KB. Tinybird never shows it again.

Outputs

secretobject
The secret
Example output
{
  "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 sourcedata_sourcetextRequired
The data source. Pick one, or give its name.
Delete rows whereconditiontextRequired
A SQL condition on the data source's columns, such as country = 'ES' or timestamp < '2026-01-01'.
Only count themdry_runtrue/false
Count the matching rows without deleting anything.

Outputs

data_sourcetext
The data source
dry_runtrue/false
True when the rows were only counted
jobobject
The delete job
job_idtext
The delete job's id, empty when only counted
rows_to_deletenumber
How many rows match, when only counted
statustext
The delete job's status, empty when only counted
Example output
{
  "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

SecretnametextRequired
The secret. Pick one, or give its name.

Outputs

deletedtrue/false
Always true once deleted
nametext
The secret deleted
Example output
{
  "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 sourcedata_sourcetextRequired
The data source. Pick one, or give its name.

Outputs

data_sourcetext
The data source emptied
emptiedtrue/false
Always true once emptied
Example output
{
  "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 sourcedata_sourcetextRequired
The data source. Pick one, or give its name.

Outputs

data_sourceobject
The data source
Example output
{
  "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

EndpointpipetextRequired
The endpoint. Pick one, or give its name.
Parametersparametersobject
A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.

Outputs

bytes_readnumber
How many bytes were read
columnslist
The columns, in order
elapsed_secondsnumber
How long it took, in seconds
pipetext
The endpoint called
row_countnumber
How many rows came back
rowslist
The rows, one object per row
rows_before_limitnumber
At least how many rows matched before any LIMIT
rows_readnumber
How many rows were read
Example output
{
  "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 IDjob_idtextRequired
The job's id, from a step that started it or 'List jobs'.

Outputs

jobobject
The job
Example output
{
  "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

PipepipetextRequired
The pipe. Pick one, or give its name.

Outputs

pipeobject
The pipe
Example output
{
  "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 sourcedata_sourcetextRequired
The data source. Pick one, or give its name.
File addressurltextRequired
The file's web address, which Tinybird downloads.
File formatfile_formattext
The file's format. Defaults to CSV.One of: csv (CSV (default)), ndjson (NDJSON (one JSON object per line)), parquet.
Existing rowsmodetext
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 wherereplace_conditiontext
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_sourcetext
The data source the file goes to
jobobject
The job
job_idtext
The id of the job Tinybird started
statustext
The job's status when it was started, usually waiting
Example output
{
  "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

countnumber
How many
data_sourceslist
The data sources
Example output
{
  "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

Kindjob_kindtext
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.
Statusstatustext
Only jobs in this status. Leave empty for all.One of: waiting, working, done, error (Failed), cancelling, cancelled.
Pipepipetext
Only jobs of this pipe. Leave empty for all.
Created aftercreated_afterdate and time
Only jobs created after this time.
Created beforecreated_beforedate and time
Only jobs created before this time.

Outputs

countnumber
How many
jobslist
The jobs
Example output
{
  "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

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

Outputs

countnumber
How many
pipeslist
The pipes
Example output
{
  "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

countnumber
How many
secretslist
The secrets
Example output
{
  "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

countnumber
How many
tokenslist
The tokens
Example output
{
  "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 pipepipetextRequired
The copy pipe. Pick one, or give its name.

Outputs

pipetext
The copy pipe
schedule_crontext
Its schedule, in cron format
schedule_statustext
Whether the schedule is running or paused
Example output
{
  "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 pipepipetextRequired
The copy pipe. Pick one, or give its name.

Outputs

pipetext
The copy pipe
schedule_crontext
Its schedule, in cron format
schedule_statustext
Whether the schedule is running or paused
Example output
{
  "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 pipepipetextRequired
The copy pipe. Pick one, or give its name.
Parametersparametersobject
A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.
Target's rowsmodetext
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

jobobject
The job
job_idtext
The id of the job Tinybird started
pipetext
The copy pipe
statustext
The job's status when it was started, usually waiting
Example output
{
  "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 pipepipetextRequired
The sink pipe. Pick one, or give its name.
Parametersparametersobject
A value for each parameter the pipe takes. Leave one empty for its default. A list is sent as comma-separated values.
File namefile_templatetext
A file name for this run instead of the pipe's own, such as daily_export_{date}.
File formatfile_formattext
A format for this run instead of the pipe's own.One of: csv, ndjson, parquet.
Compressioncompressiontext
Compress the files for this run.One of: none, gz (Gzip).
When the file existswrite_strategytext
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

jobobject
The job
job_idtext
The id of the job Tinybird started
pipetext
The sink pipe
statustext
The job's status when it was started, usually waiting
Example output
{
  "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

SQLsqltextRequired
The SELECT to run, without a FORMAT clause. A pipe's name reads it like a table.
Parametersparametersobject
Values the query reads by name, such as user_id read with {{String(user_id)}}.

Outputs

bytes_readnumber
How many bytes were read
columnslist
The columns, in order
elapsed_secondsnumber
How long it took, in seconds
row_countnumber
How many rows came back
rowslist
The rows, one object per row
rows_before_limitnumber
At least how many rows matched before any LIMIT
rows_readnumber
How many rows were read
Example output
{
  "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

SecretnametextRequired
The secret. Pick one, or give its name.
ValuevaluetextRequired
The secret's value, at most 8 KB. Tinybird never shows it again.

Outputs

secretobject
The secret
Example output
{
  "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"
  }
}

On this page