> ## Documentation Index > Fetch the complete documentation index at: https://docs.ledgerup.ai/llms.txt > Use this file to discover all available pages before exploring further. # List accounts with usage for a time range. > Returns a page of accounts with usage aggregated by metric or currency. Metric sorting requires exactly one of metric_id or currency. ## OpenAPI ````yaml /openapi/ledgerup-engine.json get /v2/accounts/usage openapi: 3.1.0 info: title: LedgerUp API version: 0.1.0 description: OpenAPI contract for the LedgerUp API. servers: [] security: [] tags: - name: Health - name: Customers - name: Accounts - name: Grants - name: Currencies description: Currencies discovered from reported usage events. - name: Metrics - name: Refill Configurations description: Automatic balance refill thresholds and targets for an account and metric. - name: Events description: >- Individual usage events reported against an account and either a metric or currency. - name: Test description: Endpoints for test environment maintenance. - name: Products x-group: Billing description: Sellable catalog objects. Products can map to Stripe products. - name: Prices x-group: Billing description: >- Simple commercial terms for a product. Contract lines can reference a price or a rate card, but not both. - name: Rate Cards x-group: Billing description: Reusable rating policies that convert engine facts into billable amounts. - name: Contracts x-group: Billing description: >- Subscription-like commercial agreements. Contracts own contract lines and cancellation state. - name: Invoice Preview x-group: Billing description: Read-only preview of LedgerUp invoice lines before any Stripe write. paths: /v2/accounts/usage: get: tags: - Accounts summary: List accounts with usage for a time range. description: >- Returns a page of accounts with usage aggregated by metric or currency. Metric sorting requires exactly one of metric_id or currency. operationId: listAccountUsage parameters: - name: start_at in: query required: true schema: $ref: '#/components/schemas/UnixTimestamp' description: Inclusive lower bound for event occurrence time. - name: end_at in: query required: true schema: $ref: '#/components/schemas/UnixTimestamp' description: Exclusive upper bound for event occurrence time. - name: aggregation in: query required: false schema: $ref: '#/components/schemas/UsageAggregation' - name: limit in: query required: false schema: type: integer format: int64 minimum: 1 maximum: 100 default: 100 description: Maximum number of records to return. Defaults to 100. - name: starting_after in: query required: false schema: type: string description: Return the next records after this account id. description: Cursor account id from the previous page. - name: sort in: query required: false schema: type: string enum: - created_at - customer_name - metric_ascending - metric_descending default: created_at description: Account ordering. Metric ordering requires metric_id or currency. - name: metric_id in: query required: false schema: type: string description: LedgerUp metric identifier. example: metric_0194f4e3a2b77c6aa91c4f6b4db2a980 pattern: ^metric_[0-9a-f]{32}$ description: Metric used for metric_ascending or metric_descending sorting. - name: currency in: query required: false schema: type: string pattern: ^[A-Za-z]{3}$ example: usd description: >- Currency used for metric_ascending or metric_descending sorting. Normalized to lowercase. responses: '200': description: Page of accounts and aggregated usage. content: application/json: schema: $ref: '#/components/schemas/AccountUsageList' '400': $ref: '#/components/responses/BadRequestText' '401': $ref: '#/components/responses/UnauthorizedText' '403': $ref: '#/components/responses/ForbiddenText' '408': $ref: '#/components/responses/RequestTimeoutText' '422': $ref: '#/components/responses/UnprocessableText' '429': $ref: '#/components/responses/RateLimitedText' '500': $ref: '#/components/responses/InternalServerErrorText' security: - LedgerUpApiKey: [] components: schemas: UnixTimestamp: type: integer format: int64 description: Unix timestamp in seconds. example: 1767225600 UsageAggregation: type: string description: >- Aggregation applied to corrected usage events. latest returns the quantity from the event with the latest occurred_at; ties use accepted_at then event ID. count returns the number of events. enum: - sum - min - max - avg - latest - count default: sum example: sum AccountUsageList: type: object additionalProperties: false properties: data: type: array items: $ref: '#/components/schemas/AccountUsage' has_more: type: boolean description: True when additional records are available after the returned page. example: false required: - data - has_more AccountUsage: type: object additionalProperties: false properties: account: $ref: '#/components/schemas/Account' events_consumed: type: array items: $ref: '#/components/schemas/AccountMetricUsage' required: - account - events_consumed Account: type: object additionalProperties: false properties: id: type: string description: LedgerUp account identifier. example: account_0194f4e3a2b77c6aa91c4f6b4db2a980 pattern: ^account_[0-9a-f]{32}$ external_id: type: - string - 'null' description: >- Optional caller-supplied external identifier. Maximum 256 Unicode scalar values. maxLength: 256 example: crm_acme_001 ledgerup_customer_id: type: - string - 'null' format: uuid description: Optional LedgerUp billing customer UUID. example: 0194f4e3-a2b7-7c6a-a91c-4f6b4db2a980 name: type: string description: Human-readable name. Maximum 256 Unicode scalar values. maxLength: 256 example: Acme description: type: - string - 'null' description: Optional description. Maximum 2048 Unicode scalar values. maxLength: 2048 example: Usage tracked for Acme. created_at: $ref: '#/components/schemas/UnixTimestamp' updated_at: $ref: '#/components/schemas/UnixTimestamp' archived_at: anyOf: - $ref: '#/components/schemas/UnixTimestamp' - type: 'null' required: - id - external_id - ledgerup_customer_id - name - description - created_at - updated_at - archived_at AccountMetricUsage: type: object additionalProperties: false properties: metric_id: type: string description: >- LedgerUp metric identifier, or the lowercase currency code for currency usage. example: metric_0194f4e3a2b77c6aa91c4f6b4db2a980 pattern: ^(metric_[0-9a-f]{32}|[a-z]{3})$ currency: type: - string - 'null' description: >- Lowercase currency code for currency usage. Null for normal metric usage. example: usd pattern: ^[a-z]{3}$ metric_name: type: - string - 'null' description: Metric name. Null for currency usage. example: Tokens measurement_units: $ref: '#/components/schemas/MeasurementUnits' quantity: type: string description: Summed decimal quantity serialized as a string. example: '1250.5' pattern: ^-?\d+(\.\d+)?$ required: - metric_id - currency - metric_name - measurement_units - quantity MeasurementUnits: type: - string - 'null' description: >- Optional unit of measure for the metric, such as m, ft, seconds, or tokens. maxLength: 256 example: m responses: BadRequestText: description: >- Bad request, invalid header, invalid amount/quantity/currency, or text validation failure. content: text/plain: schema: type: string UnauthorizedText: description: Missing or invalid API key. content: text/plain: schema: type: string example: Invalid API key ForbiddenText: description: >- API key lacks the required permission, or reset was attempted outside the test namespace. content: text/plain: schema: type: string RequestTimeoutText: description: Request exceeded the 30 second timeout. content: text/plain: schema: type: string UnprocessableText: description: >- Semantically invalid request, such as a service period with start greater than end. content: text/plain: schema: type: string RateLimitedText: description: Rate limit exceeded. content: text/plain: schema: type: string example: rate limit exceeded InternalServerErrorText: description: Internal server error or queue failure. content: text/plain: schema: type: string securitySchemes: LedgerUpApiKey: type: apiKey in: header name: x-api-key description: LedgerUp API Key. x-displayName: LedgerUp API Key ````