Events API¶

Use the Events API to send JSON and NDJSON data to Tinybird in a high-throughput streaming way. You can send single events or entire batches of events using Gzip compression. See Events API reference.

Send single JSON events¶

You can send single JSON events to the Events API by including the JSON event in the request body. Supported event formats are JSON and newline delimited JSON (NDJSON).

For example, to send an single NDJSON event using cURL:

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

The name parameter defines the name of the data source in which to insert events. To append data to an existing data source, the DATASOURCE:APPEND scope is required.

Send batches of JSON events¶

Sending batches of events helps you achieve much higher total throughput than sending single events. You can send batches of JSON events to the Events API by formatting the events as NDJSON (newline delimited JSON). Each single JSON event must be separated by a newline (\n) character.

The following example shows how to send a batch of NDJSON events using cURL:

curl \
-H "Authorization: Bearer <import_token>" \
-d $'{"date": "2020-04-05", "city": "Chicago"}\n{"date": "2020-04-05", "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. To append data to an existing data source, the DATASOURCE:APPEND scope is required.

Limits¶

The Events API delivers a default capacity of:

• Up to 1000 requests per second per data source
• Up to 20 MB per second per data source
• Up to 10 MB per request per data source.

Rate limit headers¶

The Events API returns the following headers with the response:

Check the payload size¶

To avoid hitting the request limit size, you can check your payload size before sending. For example:

echo '{"date": "2020-04-05", "city": "Chicago"}' | wc -c | awk '{print $1/1024/1024 " MB"}'

Compress the data you send¶

You can compress the data you send to the Events API using Gzip. Compressing events adds overhead to the ingestion process, which can introduce latency, although it's typically minimal.

Here is an example of sending a JSON event compressed with Gzip from the command line:

echo '{"timestamp":"2022-10-27T11:43:02.099Z","transaction_id":"8d1e1533-6071-4b10-9cda-b8429c1c7a67","name":"Bobby Drake","email":"bobby.drake@pressure.io","age":42,"passport_number":3847665,"flight_from":"Barcelona","flight_to":"London","extra_bags":1,"flight_class":"economy","priority_boarding":false,"meal_choice":"vegetarian","seat_number":"15D","airline":"Red Balloon"}' | gzip > body.gz 

curl \
    -X POST 'https://api.tinybird.co/v0/events?name=gzip_events_example' \
    -H "Authorization: Bearer <AUTH_TOKEN>" \
    -H "Content-Encoding: gzip" \
    --data-binary @body.gz

Write operation acknowledgements¶

When you send data to the Events API, you usually receive an HTTP202 response, which indicates that the request was successful, although it doesn't confirm that the data has been committed into the underlying database. This is useful when guarantees on writes aren't strictly necessary.

Typically, it takes under two seconds to receive a response from the Events API. For example:

curl \
    -X POST 'https://api.tinybird.co/v0/events?name=events_example' \
    -H "Authorization: Bearer <AUTH_TOKEN>" \
    -d $'{"timestamp":"2022-10-27T11:43:02.099Z"}'

< HTTP/2 202 
< content-type: application/json
< content-length: 42
< 
{"successful_rows":2,"quarantined_rows":0}

If your use case requires absolute guarantees that data is committed, use the wait parameter. The wait parameter is a boolean that accepts a value of true or false. A value of false is the default behavior, equivalent to omitting the parameter entirely.

Using wait=true with your request asks the Events API to wait for acknowledgement that the data you sent has been committed into the underlying database. You then receive an HTTP200 response that confirms data has been committed.

Adding wait=true to your request can result in a slower response time. Use a timeout of at least 10 seconds when waiting for the response. For example:

curl \
    -X POST 'https://api.tinybird.co/v0/events?name=events_example&wait=true' \
    -H "Authorization: Bearer <AUTH_TOKEN>" \
    -d $'{"timestamp":"2022-10-27T11:43:02.099Z"}'

< HTTP/2 200 
< content-type: application/json
< content-length: 42
< 
{"successful_rows":2,"quarantined_rows":0}