> ## 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 latest state of a plan



## OpenAPI

````yaml /openapi.yaml get /plans/{planId}/state
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/{planId}/state:
    parameters:
      - $ref: '#/components/parameters/planId'
    get:
      tags:
        - Plan
      summary: Retrieve the latest state of a plan
      operationId: getLastPlanState
      responses:
        '200':
          description: Latest plan state.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnvelopedTimedPlanState'
        '401':
          $ref: '#/components/responses/NotAuthenticated'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    planId:
      name: planId
      description: The plan UUID.
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/UUID'
  schemas:
    EnvelopedTimedPlanState:
      type: object
      properties:
        item:
          $ref: '#/components/schemas/TimedPlanState'
        agencyId:
          $ref: '#/components/schemas/AgencyId'
        planId:
          $ref: '#/components/schemas/PlanId'
    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
    TimedPlanState:
      type: object
      readOnly: true
      properties:
        planVersion:
          description: The corresponding plan's version.
          example: 2
          allOf:
            - $ref: '#/components/schemas/PlanVersion'
        timestamp:
          $ref: '#/components/schemas/DateTime'
        state:
          $ref: '#/components/schemas/PlanState'
    AgencyId:
      type: string
      description: The agency id.
      readOnly: true
      pattern: ^BLD[0-9]{7}_[a-zA-Z0-9-._~:@!$,]+$
      example: BLD1234567_production
    PlanId:
      description: The plan id.
      readOnly: true
      example: 4cbd0ab8-282c-4b30-b981-29e1ed8a2016
      allOf:
        - $ref: '#/components/schemas/UUID'
    EnvelopedErrors:
      type: object
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error'
    PlanVersion:
      type: integer
      description: The plan version.
      readOnly: true
      minimum: 1
      example: 42
    DateTime:
      type: string
      description: >-
        A full calendar date time, expressed in the ISO8601 **date** format:
        YYYY-MM-DDThh:mm:ssZ.
      example: '2019-11-15T12:34:56Z'
    PlanState:
      type: string
      readOnly: true
      description: |
        The corresponding plan's state.
          - waiting: The plan was received and is awaiting processing.
          - processing: The plan is being processed.
          - preOptimizing: The plan is being optimized while awaiting traffic or other information.
          - preOptimized: While still awaiting traffic or other information, one of the following events has occurred:
              no better solution can be produced, or the optimization period has reached its limit.
              Note that 'preOptimized' should be followed by 'optimizing' and 'optimized'.
          - optimizing: The plan is being optimized with all required information.
          - optimized: This state can be triggered by one of the following events:
              no better solution can be produced, or the optimization period has reached its limit.
          - stopped: The plan's awaiting optimizations were canceled.
          - deleted: The plan was deleted and awaiting optimizations were canceled.
          - interrupted: The plan was either updated, stopped or deleted during its optimization.
      enum:
        - waiting
        - processing
        - preOptimizing
        - preOptimized
        - optimizing
        - optimized
        - stopped
        - deleted
        - interrupted
    Error:
      type: object
      readOnly: true
      properties:
        code:
          type: string
        message:
          type: string
        properties:
          $ref: '#/components/schemas/ErrorProperties'
      required:
        - message
        - code
    ErrorProperties:
      type: object
      additionalProperties:
        type: string
  responses:
    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'
    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

````