> ## 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.

# List billing periods

> Get your billing periods, newest first. Use a period's `id` with [Get usage /v2](/api-reference/usage/get-usage-v2) to check its usage. This endpoint is free.



## OpenAPI

````yaml /api-reference/openapi.json get /periods
openapi: 3.1.0
info:
  title: Meer API
  version: 1.3.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:
  /periods:
    get:
      tags:
        - Usage
      summary: List billing periods
      description: >-
        Get your billing periods, newest first. Use a period's `id` with [Get
        usage /v2](/api-reference/usage/get-usage-v2) to check its usage. This
        endpoint is free.
      operationId: getBillingPeriods
      parameters:
        - name: limit
          in: query
          required: false
          description: Number of billing periods per page.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: cursor
          in: query
          required: false
          description: Use next_cursor from the previous response to get the next page.
          schema:
            type: string
      responses:
        '200':
          description: Your billing periods.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingPeriodPage'
              example:
                customer_name: acme_corp
                data:
                  - id: 123
                    type: monthly
                    start_date: '2026-10-01T00:00:00Z'
                    end_date: '2026-11-01T00:00:00Z'
                next_cursor: null
        '400':
          description: Invalid query parameters or cursor.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              example:
                error: page size must be an integer between 1 and 100
        '401':
          description: Missing API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              example:
                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'
              example:
                error: invalid API key
        '500':
          description: Server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              example:
                error: unable to process request
components:
  schemas:
    BillingPeriodPage:
      type: object
      required:
        - customer_name
        - data
        - next_cursor
      properties:
        customer_name:
          type: string
          description: The authenticated account.
        data:
          type: array
          items:
            $ref: '#/components/schemas/BillingPeriod'
          description: Billing periods, newest first.
        next_cursor:
          type:
            - string
            - 'null'
          description: >-
            Pass as cursor for the next page. null means there are no more
            periods.
    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.
    BillingPeriod:
      type: object
      required:
        - id
        - type
        - start_date
        - end_date
      properties:
        id:
          type: integer
          format: int64
          description: Use this id with GET /v2/usage_stats to check usage for the period.
          minimum: 1
        type:
          type: string
          enum:
            - monthly
            - annual
        start_date:
          type: string
          format: date-time
          description: Inclusive start of the billing period, in UTC.
        end_date:
          type: string
          format: date-time
          description: Exclusive end of the billing period, in UTC.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: '`Authorization: Bearer <YOUR_API_KEY>`. The `Bearer` prefix is optional.'
      bearerFormat: API key

````

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