51 lines
2.3 KiB
Plaintext
51 lines
2.3 KiB
Plaintext
---
|
|
title: "Batch Track Usage"
|
|
openapi: "openapi POST /v1/balances.batch_track"
|
|
---
|
|
|
|
import { DynamicParamField } from "/snippets/dynamic-param-field.jsx";
|
|
import { DynamicResponseField } from "/snippets/dynamic-response-field.jsx";
|
|
import { DynamicResponseExample } from "/snippets/dynamic-response-example.jsx";
|
|
|
|
<Note>
|
|
Batch track enqueues up to **1000 usage events** in a single request. Items are validated synchronously, then enqueued for asynchronous processing. The response returns **202 immediately** without balance information — balances are deducted by background workers.
|
|
|
|
Use this when you're sending high volumes of tracking events and don't need an immediate balance read for each one.
|
|
</Note>
|
|
|
|
### Common Use Cases
|
|
|
|
<CodeGroup>
|
|
|
|
```typescript Batch many customers
|
|
await autumn.balances.batchTrack([
|
|
{ customerId: "cus_alice", featureId: "ai_messages", value: 1 },
|
|
{ customerId: "cus_bob", featureId: "ai_messages", value: 1 },
|
|
{ customerId: "cus_carol", featureId: "ai_messages", value: 3 },
|
|
]);
|
|
```
|
|
|
|
```typescript Mixed features and entities
|
|
await autumn.balances.batchTrack([
|
|
{ customerId: "cus_123", featureId: "ai_messages", value: 5 },
|
|
{ customerId: "cus_123", featureId: "api_calls", value: 12 },
|
|
{ customerId: "cus_123", featureId: "seats", entityId: "team_a", value: 1 },
|
|
]);
|
|
```
|
|
|
|
</CodeGroup>
|
|
|
|
### Partial-Failure Semantics
|
|
|
|
Batch track is designed for fire-and-forget metering. On partial failure, **the endpoint still returns 202** and logs the failed items server-side. Clients should NOT retry the batch — retrying re-enqueues the already-succeeded items, which causes double-deduction. The trade-off is silent loss of the small subset that didn't enqueue vs. duplicate processing of the much larger subset that did. For event-logging workloads, gaps are preferable to duplicates.
|
|
|
|
A 503 is returned only when **zero items were successfully enqueued** (the queue is entirely unavailable). In that case the whole request is safe to retry.
|
|
|
|
If your workload requires per-item delivery guarantees, use the [single-event track endpoint](/api-reference/core/track) with client-side retry semantics instead.
|
|
|
|
### Limits
|
|
|
|
- **Maximum batch size:** 1000 items per request
|
|
- **Minimum batch size:** 1 item
|
|
- **Rate limit:** 10 requests/second per organization (separate bucket from the single `/v1/balances.track` limiter)
|