> ## Documentation Index > Fetch the complete documentation index at: https://developers.kardinal.ai/llms.txt > Use this file to discover all available pages before exploring further. # Retrieves a collection of plans > At the moment, retrieving a collection of plans is not paginated by default. The paging is performed when at least one of the paging query parameters (`page` or `itemsPerPage`) is present with a valid value. The default values are used like this: - if `page` is present and `itemsPerPage` is absent, the paging is performed with a default value for `itemsPerPage`, - if `itemsPerPage` is present and `page` is absent, the paging is performed with a default value for `page`, - but if both `page` and `itemsPerPage` are absent, no paging is performed. ## OpenAPI ````yaml /openapi.yaml get /agencies/{agencyId}/plans openapi: 3.0.3 info: title: Kardinal ARO API version: 2.55.0 description: This document specifies the REST API of Kardinal ARO v2. contact: url: https://kardinal.ai/ email: contact@kardinal.ai servers: - url: /api/v2 security: - access_token: [] tags: - name: Authenticate description: How to authenticate, and manage the access and refresh tokens. - name: Plan description: How to create, retrieve, update and delete plans. - name: Resource description: How to create, retrieve, update and delete resources in a plan. - name: Order description: How to create, retrieve, update and delete orders in a plan. - name: SimplePlan description: How to create a plan through the use of a simple plan. paths: /agencies/{agencyId}/plans: parameters: - $ref: '#/components/parameters/agencyId' get: tags: - Plan summary: Retrieves a collection of plans description: > At the moment, retrieving a collection of plans is not paginated by default. The paging is performed when at least one of the paging query parameters (`page` or `itemsPerPage`) is present with a valid value. The default values are used like this: - if `page` is present and `itemsPerPage` is absent, the paging is performed with a default value for `itemsPerPage`, - if `itemsPerPage` is present and `page` is absent, the paging is performed with a default value for `page`, - but if both `page` and `itemsPerPage` are absent, no paging is performed. operationId: getPlans parameters: - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/itemsPerPage' - $ref: '#/components/parameters/archived' responses: '200': description: Plan collection response in a light representation. content: application/json: schema: $ref: '#/components/schemas/EnvelopedPlansLight' '401': $ref: '#/components/responses/NotAuthenticated' '403': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' components: parameters: agencyId: name: agencyId description: The agency id. in: path required: true schema: $ref: '#/components/schemas/AgencyId' page: name: page description: The page number of a paginated list of records. in: query required: false schema: type: integer minimum: 1 default: 1 example: 1 itemsPerPage: name: itemsPerPage description: The number of items per page in a paginated list of records. in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 example: 30 archived: name: archived description: Indicates if and how archived items should be part of the result. in: query schema: type: string enum: - excluded - included - only default: excluded schemas: EnvelopedPlansLight: type: object properties: items: type: array items: $ref: '#/components/schemas/PlanLight' agencyId: $ref: '#/components/schemas/AgencyId' paging: $ref: '#/components/schemas/Paging' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' AgencyId: description: The agency id. readOnly: true example: LND_Agency-42 allOf: - $ref: '#/components/schemas/RegexPrefixedIdValidation' PlanLight: type: object description: A plan without resources, orders, ... for a date and agency. properties: id: $ref: '#/components/schemas/PlanId' agencyId: $ref: '#/components/schemas/AgencyId' version: $ref: '#/components/schemas/PlanVersion' running: type: boolean description: To know if the plan is running. readOnly: true status: $ref: '#/components/schemas/PlanStatus' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' properties: $ref: '#/components/schemas/Properties' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' Paging: type: object properties: total: type: integer readOnly: true description: The total number of items in the requested collection. example: 142 totalPages: type: integer readOnly: true description: The total number of pages in the requested collection. example: 5 page: type: integer readOnly: true description: The current page of items. example: 2 nextPage: type: integer readOnly: true description: The next available page of items. nullable: true example: 3 previousPage: type: integer readOnly: true description: The previous page of items. nullable: true example: 1 itemsPerPage: type: integer readOnly: true default: 20 maximum: 100 description: The number of items per page, set internally or by the request. example: 30 description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' EnvelopedErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' RegexPrefixedIdValidation: type: string description: An id beginning with a prefix and an underscore. pattern: ^[A-Z]{3,6}_[a-zA-Z0-9-._~:@!$,]+$ PlanId: description: The plan id. readOnly: true example: plan-AB allOf: - $ref: '#/components/schemas/RegexIdValidation' PlanVersion: type: integer description: The plan version. readOnly: true minimum: 1 example: 42 PlanStatus: type: object readOnly: true properties: planVersionInSolution: description: The plan version taken into account in the current solution. allOf: - $ref: '#/components/schemas/PlanVersion' waitingRoom: description: >- If the maximum number of simultaneous running plans has already been reached, the plan waits in the waiting room for one of the running plans to finish. allOf: - $ref: '#/components/schemas/PlanStatusVersion' waitingTraffic: description: The plan is waiting for its traffic coefficients to be computed. allOf: - $ref: '#/components/schemas/PlanStatusVersion' creation: description: The plan is being created in order to be optimized. allOf: - $ref: '#/components/schemas/PlanStatusVersion' optimization: description: The plan is being optimized. allOf: - $ref: '#/components/schemas/PlanStatusVersion' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' Properties: type: object additionalProperties: type: string description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' Error: type: object readOnly: true properties: code: type: string description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' message: type: string description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' properties: $ref: '#/components/schemas/ErrorProperties' required: - message - code description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' RegexIdValidation: type: string description: >- At least one character among those allowed: unaccented alpha-numeric characters, "-", ".", "_", "~", ":", "@", "!", "$", ",". pattern: ^[a-zA-Z0-9-._~:@!$,]+$ PlanStatusVersion: type: object properties: waitingVersion: description: The version currently waiting. allOf: - $ref: '#/components/schemas/PlanVersion' runningVersion: description: The version currently running. allOf: - $ref: '#/components/schemas/PlanVersion' description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' ErrorProperties: type: object additionalProperties: type: string description: '[TO_VALIDATE] Description pending review by a Kardinal engineer.' responses: NotAuthenticated: description: The caller is not authenticated. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' Unauthorized: description: The caller is not authorized to perform this action. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' NotFound: description: The specified resource was not found. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' InternalServerError: description: An internal server error has occurred. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' securitySchemes: access_token: type: http scheme: bearer bearerFormat: JWT ````