> ## Documentation Index > Fetch the complete documentation index at: https://lava.so/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get usage statistics > Get daily aggregated usage statistics for a specific time period with optional filtering by customer or meter. Helps analyze AI usage patterns and costs. ## OpenAPI ````yaml /openapi.json get /usage openapi: 3.0.0 info: title: Lava API description: >- Lava API enables businesses to implement usage-based billing for AI services. This API allows tracking, managing, and billing for third-party AI API usage through a forwarding system. version: 1.0.0 contact: name: Lava support url: https://www.lava.so/contact servers: - url: https://api.lava.so/v1/ description: Lava API v1 security: [] tags: - name: Authentication - name: Core Endpoints - name: Models - name: Services - name: Requests - name: Wallet - name: Payment Methods - name: Spend Keys - name: Usage - name: Checkout Sessions - name: Customers - name: Plans - name: Subscriptions - name: Meters - name: Webhooks - name: Secret Keys - name: Credit Bundles - name: Gateway Settings - name: Skills - name: News Data - name: Search - name: Enrich paths: /usage: get: tags: - Usage summary: Get usage statistics description: >- Get daily aggregated usage statistics for a specific time period with optional filtering by customer or meter. Helps analyze AI usage patterns and costs. parameters: - name: start in: query required: true schema: type: string format: date description: >- Start of the usage period (inclusive) in ISO 8601 format, this also sets the timezone of the grouped usage data example: '2023-05-01T00:00:00Z' - name: end in: query schema: type: string format: date description: >- End of the usage period (inclusive) in ISO 8601 format, if not specified, usage data will be returned up to the current time example: '2023-05-31T23:59:59Z' - name: customer_id in: query schema: type: string description: Filter usage by customer ID example: con_test_01EXAMPLE00000000000000001 - name: meter_id in: query schema: type: string description: Filter usage by meter ID example: prd_test_01EXAMPLE00000000000000001 - name: metadata_filters in: query schema: type: string description: >- Filter usage by metadata key-value pairs. Must be a JSON array of [key, value] pairs, where both key and value are strings. Keys must contain only ASCII letters, numbers, and underscores (no spaces or special characters). Example: [['user_id', '123'], ['session_id', 'abc']] example: '[["user_id", "123"], ["session_id", "abc"]]' responses: '200': description: Usage statistics content: application/json: schema: $ref: '#/components/schemas/Usage' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' examples: usage_start_date_missing: summary: Start date missing value: error: message: Start date is required. code: usage_start_date_missing status: 400 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: auth_header_missing: summary: Authorization header missing value: error: message: >- Authorization header is required. Please include an 'Authorization' header with your request. code: auth_header_missing status: 401 '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' examples: rest_internal_server_error: summary: Internal server error value: error: message: >- An internal server error occurred while processing your request. code: rest_internal_server_error status: 500 security: - Auth: [] components: schemas: Usage: type: object properties: items: type: array items: type: object properties: date: type: string format: date example: '2023-05-15' description: Date of the usage in YYYY-MM-DD format start: type: string format: date-time example: '2023-05-15T00:00:00Z' description: Start of the usage period in ISO 8601 format end: type: string format: date-time example: '2023-05-15T23:59:59Z' description: End of the usage period in ISO 8601 format total_requests: type: integer example: 100 description: Total number of requests on this date total_usage_tokens: type: integer example: 45823 description: Total number of tokens consumed on this date total_cost: type: string example: '2.5741000000' description: >- Total base AI provider cost in USD on this date (high precision decimal as string) total_charge: type: string example: '0.2574100000' description: >- Total merchant fee/markup amount in USD on this date (high precision decimal as string) required: - date - total_requests - total_usage_tokens - total_cost - total_charge totals: type: object properties: total_requests: type: integer example: 1000 description: Total number of requests across all dates total_usage_tokens: type: integer example: 458230 description: Total number of tokens consumed across all dates total_cost: type: string example: '25.7410000000' description: >- Total base AI provider cost in USD across all dates (high precision decimal as string) total_charge: type: string example: '2.5741000000' description: >- Total merchant fee/markup amount in USD across all dates (high precision decimal as string) required: - total_requests - total_usage_tokens - total_cost - total_charge required: - items - totals Error: type: object properties: error: type: object properties: message: type: string description: Human-readable error message describing what went wrong example: Invalid authentication credentials code: type: string description: Machine-readable error code describing what went wrong example: forward_token_json_invalid status: type: integer description: HTTP status code of the error example: 400 issues: type: array items: type: object properties: path: type: array items: type: string description: Path to the field that caused the validation error message: type: string description: Error message describing the validation issue required: - path - message description: >- Optional array of specific validation issues with their paths and messages example: - path: - model message: 'Missing required field: model' - path: - messages - '0' - content message: Invalid message content format required: - message - code - status required: - error securitySchemes: Auth: type: http scheme: bearer description: >- Bearer token authentication used for standard API calls. Format: 'Bearer YOUR_API_KEY' ````