Events API

The Events API is designed to enable high throughput streaming ingestion into Tinybird from an easy to use HTTP API.

On this page you will find details of how to use the Events API to perform various tasks. You can find the Events API Reference here.

Sending individual JSON events

You can send individual JSON events to the Events API by including the JSON event in the Request body.

For example, to send an individual JSON event using cURL:

Sending individual JSON events
curl \
-H "Authorization: Bearer <DATASOURCE:APPEND token>" \
-d '{"date": "2020-04-05 00:05:38", "city": "Chicago"}' \
'https://api.tinybird.co/v0/events?name=events_test'

The name parameter defines the name of the Data Source in which to insert events. If the Data Source does not exist, Tinybird will create the Data Source by inferring the schema of the JSON.

The Auth Token used to send data to the Events API must have the appropriate scopes. To append data to an existing Data Source, the DATASOURCE:APPEND scope is required. If the Data Source does not already exist, the DATASOURCE:CREATE scope is required to create the new Data Source.

Sending batches of JSON events

You can send batches of JSON events to the Events API by formatting the events as NDJSON (newline delimited JSON). Each individual JSON event should be separated by a newline (\n) character.

Sending batches of events enables you to achieve much higher total throughput than sending individual events.

Sending batches of JSON events
curl \
-H "Authorization: Bearer <import_token>" \
-d $'{"date": "2020-04-05 00:05:38", "city": "Chicago"}\n{"date": "2020-04-05 00:07:22", "city": "Madrid"}\n' \
'https://api.tinybird.co/v0/events?name=events_test'

The name parameter defines the name of the Data Source in which to insert events. If the Data Source does not exist, Tinybird will create the Data Source by inferring the schema of the JSON.

The Auth Token used to send data to the Events API must have the appropriate scopes. To append data to an existing Data Source, the DATASOURCE:APPEND scope is required. If the Data Source does not already exist, the DATASOURCE:CREATE scope is required to create the new Data Source.

Limits

The Events API will deliver an out of the box capacity of:

  • Up to 1000 requests/second

  • Up to 20MB/s

Throughput above these limits is offered as best-effort.

The Events API is able to scale well beyond these limits. If you are reaching these limits, please contact support@tinybird.co.