Skip to main content
POST
/
v1
/
balances.batch_track
Typescript (SDK)
import { Autumn } from 'autumn-js'

const autumn = new Autumn()

const result = await autumn.batchTrack([
  {
    customerId: "cus_123",
    featureId: "messages",
    value: 1,
  },
  {
    customerId: "cus_123",
    eventName: "message.sent",
    value: 1,
  },
]);
from autumn_sdk import Autumn

autumn = Autumn(secret_key="am_sk_test...")

res = autumn.batch_track(
    request=[
        {
            "customer_id": "cus_123",
            "feature_id": "messages",
            "value": 1,
        },
        {
            "customer_id": "cus_123",
            "event_name": "message.sent",
            "value": 1,
        },
    ],
)
curl --request POST \
  --url https://api.useautumn.com/v1/balances.batch_track \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: <x-api-version>' \
  --data '
[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_123",
    "event_name": "message.sent",
    "value": 1
  }
]
'
{
  "success": true
}
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.

​
Common Use Cases

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

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

​
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 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)

​
Body Parameters

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

​
x-api-version
string
default:2.3.0
required

Body

application/json
Required array length: 1 - 1000 elements
​
customer_id
string
required

The ID of the customer.

​
feature_id
string

The ID of the feature to track usage for. Required if event_name is not provided.

​
entity_id
string

The ID of the entity for entity-scoped balances (e.g., per-seat limits).

​
event_name
string

Event name to track usage for. Use instead of feature_id when multiple features should be tracked from a single event.

Minimum string length: 1
​
value
number

The amount of usage to record. Defaults to 1. Use negative values to credit balance (e.g., when removing a seat).

​
properties
object

Additional properties to attach to this usage event.

​
timestamp
integer

Unix timestamp in milliseconds to use for the usage event. Defaults to the current time.

Required range: 0 < x <= 9007199254740991
​
async
boolean

If true, enqueue the event for asynchronous processing and return 204 immediately. The response will not include balance information.

​
lock
object
Example:
[
  {
    "customer_id": "cus_123",
    "feature_id": "messages",
    "value": 1
  },
  {
    "customer_id": "cus_123",
    "event_name": "message.sent",
    "value": 1
  }
]

Response

202 - application/json

Batch accepted. All items passed synchronous validation. Enqueue is best-effort: partial failures (some items enqueued, some not) are logged server-side and are NOT surfaced in the response body; clients must not retry on 202. See the endpoint description for full partial-failure semantics.

​
success
any
required