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

# Get Customer Usage

> Return customer usage analytics for the authenticated API key.

Includes quota tracking, call statistics, performance metrics, and cost breakdown.
Requires API key authentication.

Args:
    period: Time period for usage aggregation (default: current_month)
    api_key: Validated API key from require_api_key dependency

Returns:
    CustomerUsageResponse with complete usage data



## OpenAPI

````yaml /api-reference/openapi.json get /v1/usage
openapi: 3.1.0
info:
  title: Limitguard.ai
  description: >-
    Lead validation API: the company behind each lead checked against the NL and
    BE business registers, EU VAT and sanctions lists, plus company, KYB and
    agent wallet checks for developers and AI agents
  version: 0.1.0
servers:
  - url: https://api.limitguard.ai
security: []
paths:
  /v1/usage:
    get:
      summary: Get Customer Usage
      description: >-
        Return customer usage analytics for the authenticated API key.


        Includes quota tracking, call statistics, performance metrics, and cost
        breakdown.

        Requires API key authentication.


        Args:
            period: Time period for usage aggregation (default: current_month)
            api_key: Validated API key from require_api_key dependency

        Returns:
            CustomerUsageResponse with complete usage data
      operationId: get_customer_usage_v1_usage_get
      parameters:
        - name: period
          in: query
          required: false
          schema:
            $ref: '#/components/schemas/UsagePeriod'
            default: current_month
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomerUsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyHeader: []
components:
  schemas:
    UsagePeriod:
      type: string
      enum:
        - current_month
        - previous_month
        - last_7_days
        - last_30_days
      title: UsagePeriod
      description: Time period for usage aggregation.
    CustomerUsageResponse:
      properties:
        period:
          type: string
          title: Period
          description: Usage period
        period_start:
          type: string
          format: date-time
          title: Period Start
          description: Period start timestamp
        period_end:
          type: string
          format: date-time
          title: Period End
          description: Period end timestamp
        tier:
          type: string
          title: Tier
          description: Customer pricing tier
        quota:
          $ref: '#/components/schemas/UsageQuota'
          description: Quota information
        calls:
          $ref: '#/components/schemas/UsageCalls'
          description: Call statistics
        performance:
          $ref: '#/components/schemas/UsagePerformance'
          description: Performance metrics
        cost:
          $ref: '#/components/schemas/UsageCost'
          description: Cost breakdown
        request_id:
          type: string
          title: Request Id
          description: Request tracking ID
      type: object
      required:
        - period
        - period_start
        - period_end
        - tier
        - quota
        - calls
        - performance
        - cost
        - request_id
      title: CustomerUsageResponse
      description: Complete usage response for customer dashboard (DYN-273).
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    UsageQuota:
      properties:
        limit:
          type: integer
          minimum: 0
          title: Limit
          description: Monthly request limit
        used:
          type: integer
          minimum: 0
          title: Used
          description: Requests used in period
        remaining:
          type: integer
          minimum: 0
          title: Remaining
          description: Remaining requests
        percent_used:
          type: number
          maximum: 100
          minimum: 0
          title: Percent Used
          description: Percentage of quota used
      type: object
      required:
        - limit
        - used
        - remaining
        - percent_used
      title: UsageQuota
      description: Usage quota information.
    UsageCalls:
      properties:
        total:
          type: integer
          minimum: 0
          title: Total
          description: Total API calls
        by_endpoint:
          additionalProperties:
            type: integer
          type: object
          title: By Endpoint
          description: Calls grouped by endpoint
        by_status:
          additionalProperties:
            type: integer
          type: object
          title: By Status
          description: Calls grouped by HTTP status code
      type: object
      required:
        - total
      title: UsageCalls
      description: Call statistics.
    UsagePerformance:
      properties:
        avg_response_time_ms:
          type: number
          minimum: 0
          title: Avg Response Time Ms
          description: Average response time in ms
        p95_response_time_ms:
          type: number
          minimum: 0
          title: P95 Response Time Ms
          description: 95th percentile response time in ms
        cache_hit_rate:
          type: number
          maximum: 100
          minimum: 0
          title: Cache Hit Rate
          description: Cache hit rate percentage
      type: object
      required:
        - avg_response_time_ms
        - p95_response_time_ms
        - cache_hit_rate
      title: UsagePerformance
      description: Performance metrics.
    UsageCost:
      properties:
        total_usd:
          type: number
          minimum: 0
          title: Total Usd
          description: Total cost in USD
        by_endpoint:
          additionalProperties:
            type: number
          type: object
          title: By Endpoint
          description: Cost grouped by endpoint
      type: object
      required:
        - total_usd
      title: UsageCost
      description: Cost breakdown.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.