> ## Documentation Index
> Fetch the complete documentation index at: https://docs.unprice.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Record usage

> Queue a raw usage event for asynchronous processing.

<RequestExample>
  ```ts theme={null}
  const { result, error } = await unprice.usage.record({
    idempotencyKey: "idem_123",
    eventSlug: "completions",
    customerId: "cus_1234567890",
    properties: {
      aiMessages: 1,
      aiGenerations: 2,
      aiTools: 3,
      inputTokens: 1840,
      outputTokens: 620,
      model: "gpt-4.1-mini"
    }
  });

  if (error) {
    console.error(error.message);
    return;
  }

  console.log(result);
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "accepted": true
  }
  ```
</ResponseExample>

## Request

<ParamField body="idempotencyKey" type="string" required>
  Logical key used to deduplicate the event.
</ParamField>

<ParamField body="eventSlug" type="string" required>
  The broad event kind configured in Unprice, for example `completions`.
</ParamField>

<ParamField body="customerId" type="string">
  The customer ID. Required when the API key has no default customer binding.
</ParamField>

<ParamField body="properties" type="object" required>
  Event properties used by meters. One async event can carry multiple measured fields, for
  example `aiMessages`, `aiGenerations`, `aiTools`, `inputTokens`, and `outputTokens`.
</ParamField>

<ParamField body="timestamp" type="number">
  Optional epoch-millisecond event timestamp.
</ParamField>

`usage.record` does not block paid work. Use it for async metering, analytics, and invoice evidence,
not for request-path spend enforcement.

For async reporting, `eventSlug` names what happened. Each meter on matching features chooses which
property to aggregate from that event. That lets one `completions` event update several features such
as `ai-messages`, `ai-generations`, and `ai-tools`.