> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tirdad.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# High-Volume Ingestion

> Batch usage events with the bulk endpoint or the SDKs, and keep a high-volume sender stable under load

One request per usage event works while volume is low. Once you send more than a few events per second, batch them: fewer requests, less overhead per event, and one retry covers many events. This page covers high-volume ingestion through the bulk endpoint and the SDKs, and how to keep a sender stable when the network or Tirdad slows down.

## Batching usage events with the bulk endpoint

`POST /v1/events/bulk` takes the same event fields as a single event, in an `events` array:

* **Batch size:** 1 to 1000 events per request.
* **Body size:** up to 32 MiB. A larger body fails with `400` and the message "Request body exceeds the maximum size; split the batch into smaller requests".
* **Flush policy:** send a batch when it reaches 1000 events or after a fixed interval, such as one or two seconds, whichever comes first, so a quiet period doesn't hold events back.

How a bulk request fails decides what to resend:

* **Invalid JSON, a timestamp that isn't RFC 3339, more than 1000 events, or an oversized body** reject the whole request before any event in it is accepted.
* **An event missing `event_name` or `external_customer_id`** can fail the request after earlier events in the array were accepted.

In both cases, fix the payload and resend the whole batch. When every event carries its own `event_id` and `timestamp`, the events Tirdad already accepted collapse with their resent copies: see [Idempotency and Deduplication](https://docs.tirdad.ai/docs/core-concepts/usage-events/idempotency.md).

## Batching usage events with the SDKs

Every SDK has a bulk method. Collect events in your worker and send them in one call:

```go Go theme={null}
resp, err := client.Events.IngestEventsBulk(ctx, types.BulkIngestEventRequest{
	Events: []types.IngestEventRequest{
		{
			EventName:          "api_request",
			ExternalCustomerID: "cust_123",
			EventID:            tirdad.String("req_9f3c"),
			Timestamp:          tirdad.String("2026-10-10T14:03:00Z"),
			Properties:         map[string]string{"bytes": "1024"},
		},
		{
			EventName:          "api_request",
			ExternalCustomerID: "cust_123",
			EventID:            tirdad.String("req_9f3d"),
			Timestamp:          tirdad.String("2026-10-10T14:03:05Z"),
			Properties:         map[string]string{"bytes": "2048"},
		},
	},
})
```

```python Python theme={null}
result = client.events.ingest_events_bulk(
    events=[
        {
            "event_name": "api_request",
            "external_customer_id": "cust_123",
            "event_id": "req_9f3c",
            "timestamp": "2026-10-10T14:03:00Z",
            "properties": {"bytes": "1024"},
        },
        {
            "event_name": "api_request",
            "external_customer_id": "cust_123",
            "event_id": "req_9f3d",
            "timestamp": "2026-10-10T14:03:05Z",
            "properties": {"bytes": "2048"},
        },
    ],
)
```

```typescript TypeScript theme={null}
const result = await tirdad.events.ingestEventsBulk({
  events: [
    {
      eventName: "api_request",
      externalCustomerId: "cust_123",
      eventId: "req_9f3c",
      timestamp: "2026-10-10T14:03:00Z",
      properties: { bytes: "1024" },
    },
    {
      eventName: "api_request",
      externalCustomerId: "cust_123",
      eventId: "req_9f3d",
      timestamp: "2026-10-10T14:03:05Z",
      properties: { bytes: "2048" },
    },
  ],
});
```

Retries are off by default in every SDK. Turn them on when you create the client: see [Retrying failed SDK requests](https://docs.tirdad.ai/developers/sdks/usage.md#retrying-failed-sdk-requests).

### How the Go SDK async client sends usage events

The Go SDK also has an async client (`client.NewAsyncClientWithConfig`) that queues events in process memory and sends them from background goroutines. Know how it delivers before you bill on it:

* It sends each event as its own `POST /v1/events` request, not through the bulk endpoint.
* It doesn't set an `event_id`. Pass your own with `EnqueueWithOptions`, or a resent event can't be recognized as a copy. When you leave out the timestamp, it stamps the event at enqueue time.
* An event whose send fails is dropped once the retries configured on the parent client (`WithRetryConfig`) run out. The failure is printed only when `Debug` is on.
* `Close()` returns without waiting for queued events to be sent, so events still in memory when the process exits can be lost.
* `Enqueue` blocks while the queue is full (`MaxQueueSize`, 1000 by default).

For usage you bill on, keep events on a durable queue and send them with `IngestEventsBulk` instead.

## Keeping a high-volume sender stable

* **Cap concurrency.** Send from a fixed pool of workers, each with one request in flight, instead of opening a request per event.
* **Back off on failure.** Retry network errors, timeouts, and `5xx` responses with exponential backoff and jitter, so that many workers don't retry in lockstep.
* **Let the queue absorb outages.** Keep events on a durable queue until Tirdad accepts them, size it for the longest outage you want to ride out, and alert on the age of the oldest event in it.
* **Watch processing lag.** A `202` means Tirdad accepted the events; metering runs asynchronously behind it. The [Event Monitoring](https://docs.tirdad.ai/docs/event-ingestion/monitoring.md) endpoint returns `consumption_lag`, the number of accepted events still waiting to be processed in your environment.

> [card] [Send Usage Events with the API and SDKs](https://docs.tirdad.ai/docs/core-concepts/usage-events/sending-events.md)
>
> Authentication, single and bulk requests, and the responses to handle.

> [card] [Backfill Past Usage](https://docs.tirdad.ai/docs/core-concepts/usage-events/backfill.md)
>
> Load historical usage and get it onto draft or finalized invoices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.