> ## 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. # Retrieve the list of plans, in a light representation > 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 /plans openapi: 3.0.3 info: title: Kardinal Builder API version: 1.0.0 description: > This document specifies the REST API of Kardinal for builder users. Every endpoint applies to the single agency carried by the access token (either the sandbox agency or the production agency), which is why no agency id appears in the paths. An access token that does not grant access to exactly one agency is rejected with a `403`. contact: url: https://kardinal.ai/ email: contact@kardinal.ai servers: - url: /api/v2 security: - access_token: [] tags: - name: Plan description: How to create, retrieve, update and delete plans. - name: Solution description: How to retrieve the solution of a plan and its objectives. - name: Webhook description: How to create, retrieve, update and delete webhooks on a plan. paths: /plans: get: tags: - Plan summary: Retrieve the list of plans, in a light representation 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: getPlansLight 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' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/NotAuthenticated' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalServerError' components: parameters: 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' PlanLight: type: object description: >- A plan in a light representation (without resources, orders, constraints, ...). 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' properties: $ref: '#/components/schemas/Properties' AgencyId: type: string description: The agency id. readOnly: true pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$ example: BLD1234567_production 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 EnvelopedErrors: type: object properties: errors: type: array items: $ref: '#/components/schemas/Error' PlanId: description: The plan id. readOnly: true example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016 allOf: - $ref: '#/components/schemas/UUID' 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' Properties: type: object additionalProperties: type: string Error: type: object readOnly: true properties: code: type: string message: type: string properties: $ref: '#/components/schemas/ErrorProperties' required: - message - code UUID: type: string format: uuid description: Universally Unique Identifier. pattern: >- ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ example: cd4ce4e3-0208-4b10-b346-25f235214e4f readOnly: true 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' ErrorProperties: type: object additionalProperties: type: string responses: BadRequest: description: >- The server could not understand the request due to invalid content (bad syntax, bad format, bad values, etc). content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' NotAuthenticated: description: The caller is not authenticated. content: application/json: schema: $ref: '#/components/schemas/EnvelopedErrors' Forbidden: description: The caller is not allowed to perform this action. 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 ````