Batching

When you have more than one event to send, you do not have to make a separate request for each. Batching lets you send many events in a single POST to /v1/events. That means fewer HTTP round trips and less overhead for your backend, which is handy when you buffer events and flush them together.

The batch shape

Instead of posting one event object, post an object with an events array. Each item in the array is a normal event.

{ "events": [ { "name": "a" }, { "name": "b", "properties": { "x": 1 } } ] }

Each element is a normal event

Every object inside the events array follows the exact same rules as a single event: the same fields, the same required name, and the same property types. If you already know how to send one event, a batch is just a list of them. See Sending events for the full field list and what a single event can contain.

Example

Here the same request carries two events at once, a player_join and a purchase, both belonging to the same actor.

curl -X POST https://topstats.gg/v1/events \
  -H "Authorization: Bearer ts_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      { "name": "player_join", "_actor": "user_123" },
      {
        "name": "purchase",
        "properties": { "amount": 9.99, "currency": "USD" },
        "_actor": "user_123"
      }
    ]
  }'

How many per batch