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

# Get usage

> Lifetime request counts for the account that owns the API key, by month and by country. Free.



## OpenAPI

````yaml /api-reference/openapi.json get /usage_stats
openapi: 3.1.0
info:
  title: Meer API
  version: 1.2.0
  description: >-
    Check phone numbers against national do-not-call registers.


    Authenticate with `Authorization: Bearer <YOUR_API_KEY>`. The `Bearer`
    prefix is optional.


    Lookups use credits from your limit for the billing period. The cost varies
    by country; each response reports it in `X-Credit-Cost` and `cost`.


    Resellers must send `X-Forwarded-Host` with a unique ID for the end customer
    on every request.
  contact:
    name: API Support
    email: support@meerapi.com
servers:
  - url: https://api.meerapi.com
    description: Production
security:
  - apiKey: []
tags:
  - name: Phone Numbers
    description: Do-not-call lookups
  - name: Usage
    description: Usage for your account
paths:
  /usage_stats:
    get:
      tags:
        - Usage
      summary: Get usage
      description: >-
        Lifetime request counts for the account that owns the API key, by month
        and by country. Free.
      operationId: getUsageStats
      responses:
        '200':
          description: Usage for your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageStatsResponse'
              examples:
                usage:
                  value:
                    customer_name: acme_corp
                    total_requests: 4823
                    monthly:
                      - year: 2026
                        month: 3
                        request_count: 1500
                      - year: 2026
                        month: 4
                        request_count: 2100
                      - year: 2026
                        month: 5
                        request_count: 1223
                    by_country:
                      - country: US
                        request_count: 3200
                      - country: ES
                        request_count: 1100
                      - country: IE
                        request_count: 523
        '401':
          description: Missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                missing_key:
                  value:
                    error: >-
                      Missing API key. Please provide it as: Authorization:
                      Bearer <YOUR_KEY>
        '403':
          description: Invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                invalid_key:
                  value:
                    error: invalid API key
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                unable_to_process:
                  value:
                    error: unable to process request
components:
  schemas:
    UsageStatsResponse:
      type: object
      required:
        - customer_name
        - total_requests
        - monthly
        - by_country
      properties:
        customer_name:
          type: string
          description: The account the API key belongs to.
        total_requests:
          type: integer
          format: int64
          description: Sum of `monthly[].request_count`.
        monthly:
          type: array
          items:
            $ref: '#/components/schemas/MonthlyUsage'
          description: Oldest month first. Months with no requests may be missing.
        by_country:
          type: array
          items:
            $ref: '#/components/schemas/CountryUsage'
          description: Most requests first, then by country code.
    RequestError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        country:
          type: string
          description: '422 only: the country of the number.'
        supported_countries:
          type: array
          items:
            type: string
          description: 422 only.
    MonthlyUsage:
      type: object
      required:
        - year
        - month
        - request_count
      properties:
        year:
          type: integer
          description: UTC year.
        month:
          type: integer
          minimum: 1
          maximum: 12
          description: UTC month.
        request_count:
          type: integer
          description: Billable requests that month.
    CountryUsage:
      type: object
      required:
        - country
        - request_count
      properties:
        country:
          type: string
          description: ISO 3166-1 alpha-2 code.
        request_count:
          type: integer
          format: int64
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <YOUR_API_KEY>`. The `Bearer` prefix is optional.'
      bearerFormat: API key

````