High-Volume Ingestion

​

Batching usage events with the bulk endpoint

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

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

​

Batching usage events with the SDKs

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

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"},
        },
    ],
)

const result = await flexprice.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" },
    },
  ],
});

​

How the Go SDK async client sends usage events

• 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).

​

Streaming usage events with the Flexprice Collector

​

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 Flexprice 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 Flexprice accepted the events; metering runs asynchronously behind it. The Event Monitoring endpoint returns consumption_lag, the number of accepted events still waiting to be processed in your environment.