Pre-1.0 · one maintainer · Stripe and cards only · no SDKs (client libraries) yet · no production users yet. Docs describe v0.9.1 (29 Oct 2026) · What’s new →

List held usage

GET

/v1/usage-events/held

const url = 'http://localhost:8080/v1/usage-events/held';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url http://localhost:8080/v1/usage-events/held \
  --header 'Authorization: Bearer <token>'

Usage rows the LiteLLM integration received for a customer or meter that did not exist yet. They are kept with their idempotency keys, not billed, until you release or discard them. Grouped by external customer ID, event name and reason, most recent arrival first. Lists the 200 external customer IDs with the most recent arrivals, with every group for each; total_customers and total_rows count all held rows, listed or not. Requires usage read permission.

Authorizations

BearerAuth

Responses

200

Held groups

application/json

object

data

required

Array<object>

The usage rows still held for one external customer ID, event name and reason.

object

external_customer_id

required

The LiteLLM user value the rows carried.

string

event_name

required

The event_name the rows carried.

string

reason

required

What was missing when the rows arrived.

string

Allowed values: customer_not_found meter_not_found

rows

required

integer

total_quantity

required

Sum of the held quantities, as a decimal string.

string

first_event_at

required

string format: date-time

last_event_at

required

string format: date-time

last_received_at

required

When Hardcount last received a row for this group.

string format: date-time

customer_id

required

The customer whose external ID now matches, or empty when none does yet.

string

meter_exists

required

Whether a meter with this event_name exists now.

boolean

total_customers

required

External customer IDs with rows held, including those not listed in data.

integer

total_rows

required

Rows held, including those not listed in data.

integer

Example

{
  "data": [
    {
      "reason": "customer_not_found"
    }
  ]
}