Batch Trigger Events

Trigger multiple events in a single request

POST /apps/{appId}/batch_events

Batch Trigger Events

cURL

curl --request POST \
  --url https://api.example.com/apps/{appId}/batch_events \
  --header 'Content-Type: application/json' \
  --data '
{
  "batch": [
    {
      "name": "<string>",
      "data": {},
      "channel": "<string>",
      "channels": [
        {}
      ],
      "socket_id": "<string>",
      "info": "<string>",
      "tags": {},
      "delta": true
    }
  ]
}
'

200

{
  "batch": [
    {
      "subscription_count": 123,
      "user_count": 123
    }
  ]
}

Authentication

Same authentication requirements as Trigger Event.

Path Parameters

appId · string · required

The application ID

Request Body

batch · array · required

Array of event objects. Limited by max_event_batch_size app setting.

Each event object has the same structure as the single event endpoint:

Show Event Object

name · string · required

Event name

data · string | object · required

Event payload

channel · string

Single channel name (use either channel or channels)

channels · array

Array of channel names

socket_id · string

Socket ID to exclude from receiving this event

info · string

Comma-separated info attributes (subscription_count, user_count)

tags · object

Key-value pairs for server-side filtering

delta · boolean

Per-message delta compression control (true/false/omit)

Response

batch · array

Array of channel info objects (only returned if any event requested info). Each element corresponds to an event in the request batch.

For events that didn’t request info, returns empty object {}.

For events with info parameter:

Show Channel Info

subscription_count · number

Number of active subscriptions

user_count · number

Number of unique users (presence channels only)

If no events requested info, returns empty object {}.

Rate Limiting

Same rate limit headers as single event endpoint.

Examples

Basic Batch

curl -X POST "https://api.example.com/apps/my-app/batch_events?auth_key=key&auth_timestamp=1234567890&auth_version=1.0&body_md5=abc123&auth_signature=def456" \
  -H "Content-Type: application/json" \
  -d '{
    "batch": [
      {
        "name": "order-created",
        "channel": "orders",
        "data": "{\"order_id\": 123}"
      },
      {
        "name": "inventory-updated",
        "channel": "inventory",
        "data": "{\"item_id\": 456, \"quantity\": 10}"
      }
    ]
  }'

Response Examples

Success (No Info Requested)

{}

Processing Behavior

Sequential Processing for Delta Compression

Events in a batch are processed sequentially (not in parallel) to ensure proper delta compression state management. When multiple events target the same channel, concurrent processing would cause race conditions where all events compute deltas against the same base message, corrupting the delta chain.

Sequential processing ensures:

• Each message’s delta state is properly updated before the next message
• Correct delta compression chains for events targeting the same channel
• Deterministic ordering of events

Performance Characteristics

• Batch endpoint is significantly faster than individual requests despite sequential processing
• Single authentication overhead for entire batch
• Single HTTP round-trip
• Typical batch processing: 112-924μs for 10k subscribers with zero allocations
• Per-channel broadcasting is still parallel within each event

Error Codes

Same error codes as single event endpoint.

If any event in the batch fails validation, the entire batch is rejected and no events are triggered.

Notes

• All events in the batch must be valid or the entire request fails
• The info response array corresponds 1:1 with the request batch array
• Events without info parameter return {} in the response array
• For events with channel and channels, the first channel is used for the info response
• Batch size limits are configurable per application via max_event_batch_size
• Sequential processing ensures correct delta compression when multiple events target the same channel