Skip to main content
POST
/
api
/
v1
/
sdk
/
track
Track Usage Event (SDK)
curl --request POST \
  --url https://api.example.com/api/v1/sdk/track \
  --header 'Content-Type: application/json' \
  --data '
{
  "meter_token": "<string>",
  "customer_external_id": "<string>",
  "quantity": 123,
  "timestamp": "<string>",
  "idempotency_key": "<string>",
  "metadata": {}
}
'
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "customer_id": "550e8400-e29b-41d4-a716-446655440002",
  "meter_id": "550e8400-e29b-41d4-a716-446655440000",
  "quantity": "100",
  "timestamp": "2025-01-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:01Z",
  "meta_data": {
    "region": "us-east-1"
  }
}
The primary endpoint for sending usage events from your backend. Authenticates with an API key (no user session required).

​
Authentication

X-API-Key: org_live_<your_key>
Required scope: usage.write

​
Request Body

{
  "meter_token": "550e8400-e29b-41d4-a716-446655440000",
  "customer_external_id": "your-customer-id",
  "quantity": 100,
  "timestamp": "2025-01-15T10:30:00Z",
  "idempotency_key": "req_unique_abc123",
  "metadata": {
    "region": "us-east-1"
  }
}
​
meter_token
string
required
The unique token identifying the meter. Found in the meter’s detail page.
​
customer_external_id
string
required
Your own customer identifier. Must match the external_id on the customer record.
​
quantity
number
required
The usage quantity. Must be greater than 0.
​
timestamp
string
ISO 8601 datetime for the event. Defaults to the current time if omitted.
​
idempotency_key
string
Optional unique key. If the same key is sent again, the event is silently deduplicated.
​
metadata
object
Optional key-value pairs. Required user_id key for UNIQUE_COUNT meters.

​
Response

​
id
string
UUID of the created usage event
​
customer_id
string
Internal Fluxrate customer UUID
​
meter_id
string
Internal Fluxrate meter UUID
​
quantity
string
The tracked quantity (as string)
​
timestamp
string
Event timestamp (ISO 8601)
​
created_at
string
Record creation time
​
meta_data
object
The metadata passed with the event
{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "customer_id": "550e8400-e29b-41d4-a716-446655440002",
  "meter_id": "550e8400-e29b-41d4-a716-446655440000",
  "quantity": "100",
  "timestamp": "2025-01-15T10:30:00Z",
  "created_at": "2025-01-15T10:30:01Z",
  "meta_data": {
    "region": "us-east-1"
  }
}