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