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

# List plan instances

> This endpoint allows fetching a list of plan instances, newest first by creation time, each with the ids of its contract, its customer and its plan. Active plan instances are returned unless `status[]` says otherwise. Fetch a plan instance by id to read its charges.



## OpenAPI

````yaml /api-reference/openapi.yaml get /v1/plan-instances/
openapi: 3.1.0
info:
  title: API Reference
  version: '1.0'
  description: Aira API Reference
  x-logo:
    url: https://static.useaira.com/images/airalogo.svg
    backgroundColor: '#FFFFFF'
    altText: Aira Logo
servers:
  - url: https://api.useaira.com
    description: API base URL
security:
  - ApiKey: []
paths:
  /v1/plan-instances/:
    get:
      tags:
        - Plan Instances
      summary: List plan instances
      description: >-
        This endpoint allows fetching a list of plan instances, newest first by
        creation time, each with the ids of its contract, its customer and its
        plan. Active plan instances are returned unless `status[]` says
        otherwise. Fetch a plan instance by id to read its charges.
      parameters:
        - schema:
            type: string
            format: uuid
          in: query
          name: contractId
          required: false
          description: Only return the plan instances of this contract.
        - schema:
            type: string
            format: uuid
          in: query
          name: planId
          required: false
          description: Only return the plan instances of this plan.
        - schema:
            type: array
            items:
              type: string
              format: uuid
          in: query
          name: customerIds[]
          required: false
          description: >-
            Only return the plan instances of the contracts of these customers,
            identified by their id in our system.
        - schema:
            type: array
            items:
              type: string
              pattern: ^[a-zA-Z0-9_-]+$
          in: query
          name: customerExternalIds[]
          required: false
          description: >-
            Only return the plan instances of the contracts of these customers,
            identified by their id in your system.
        - schema:
            type: array
            items:
              type: string
              enum:
                - active
                - canceled
                - completed
          in: query
          name: status[]
          required: false
          description: >-
            Only return the plan instances in these statuses. Active plan
            instances are returned when omitted.
        - schema:
            type: integer
            default: 0
            minimum: 0
            maximum: 2147483647
          in: query
          name: offset
          required: false
          description: Number of items to skip before collecting the page.
        - schema:
            type: integer
            minimum: 1
            default: 100
            maximum: 100
          in: query
          name: limit
          required: false
          description: Maximum number of items to return per page.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: >-
                        Schema representing a plan instance in a list: a plan
                        put on one contract, with the ids of the contract, the
                        customer and the plan that it belongs to. Fetch the plan
                        instance by id to read its charges.
                      properties:
                        id:
                          description: >-
                            The unique identifier of the plan instance in our
                            system.
                          type: string
                          format: uuid
                        contractId:
                          description: >-
                            The unique identifier of the contract that the plan
                            instance belongs to.
                          type: string
                          format: uuid
                        customerId:
                          description: >-
                            The unique identifier of the customer that the
                            contract belongs to.
                          type: string
                          format: uuid
                        planId:
                          description: >-
                            The unique identifier of the plan that the plan
                            instance comes from.
                          type: string
                          format: uuid
                        status:
                          description: >-
                            The status of the plan instance: active (billed in
                            the cycles of the contract), completed (reached its
                            end) or canceled (stopped before its end).
                          type: string
                          enum:
                            - active
                            - canceled
                            - completed
                        activePlanInstanceVersionId:
                          description: >-
                            The unique identifier of the plan instance version
                            that billing uses.
                          type: string
                          format: uuid
                        plan:
                          type: object
                          description: The plan that the plan instance comes from.
                          properties:
                            id:
                              type: string
                              format: uuid
                              description: The unique identifier for this plan.
                            name:
                              type: string
                              minLength: 1
                              description: The name of the plan.
                          required:
                            - id
                            - name
                          additionalProperties: false
                      required:
                        - id
                        - contractId
                        - customerId
                        - planId
                        - status
                        - activePlanInstanceVersionId
                        - plan
                      additionalProperties: false
                    description: A list of items.
                  hasMore:
                    description: Indicates if there are more items to fetch.
                    type: boolean
                required:
                  - items
                  - hasMore
                additionalProperties: false
        '429':
          description: >-
            The tenant reached one of its limits of reads: 20 reads in flight or
            50 reads per second.
          headers:
            Retry-After:
              schema:
                type: integer
              description: The seconds to wait before the next read.
            RateLimit-Limit:
              schema:
                type: integer
              description: >-
                The limit that the read hit: 20 for the reads in flight, 50 for
                the reads per second.
            RateLimit-Remaining:
              schema:
                type: integer
              description: The reads left under that limit, which is 0.
            RateLimit-Reset:
              schema:
                type: integer
              description: >-
                The seconds to wait before the next read, as in Retry-After. The
                limit of reads per second takes new reads in the next second,
                but the limit of reads in flight takes a new read only once one
                of the reads in flight ends.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    description: >-
                      A human-readable description of the limit that the read
                      hit
                  code:
                    type: string
                    enum:
                      - too_many_reads_in_flight
                      - too_many_reads_per_second
                    description: The limit that the read hit
                required:
                  - code
                  - message
                additionalProperties: false
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      description: API Key Authentication.
      name: X-API-KEY
      in: header

````

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