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

# Get session

> Reads the state of a session started by POST /agents/execute: whether it is running, waiting in line, or finished, where it sits in its queue, and how much work that queue is holding. Cheap enough to poll while waiting for enqueued work to start.



## OpenAPI

````yaml post /agents/sessions/get
openapi: 3.1.0
info:
  title: Kaizen API
  version: 1.0.0
  description: API for the Kaizen Automation Platform
servers:
  - url: https://api.kaizenautomation.com
    description: Production server
security: []
paths:
  /agents/sessions/get:
    post:
      tags:
        - Agents
      summary: Get session
      description: >-
        Reads the state of a session started by POST /agents/execute: whether it
        is running, waiting in line, or finished, where it sits in its queue,
        and how much work that queue is holding. Cheap enough to poll while
        waiting for enqueued work to start.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                sessionId:
                  type: string
                  description: The ID of the session, as returned by POST /agents/execute
                  example: agent_conversation_thread_01k1v4m0000000000000000000
              required:
                - sessionId
        required: true
      responses:
        '200':
          description: The session
          content:
            application/json:
              schema:
                type: object
                properties:
                  sessionId:
                    type: string
                    description: The ID of the session, as returned by POST /agents/execute
                    example: agent_conversation_thread_01k1v4m0000000000000000000
                  agentId:
                    type: string
                    description: The ID of the agent running the session
                  status:
                    type: string
                    enum:
                      - Pending
                      - InProgress
                      - Completed
                      - Failed
                      - Paused
                      - WaitingInLine
                      - Sleeping
                    description: Lifecycle status of the session
                    example: WaitingInLine
                  queuePositionInLine:
                    type:
                      - integer
                      - 'null'
                    description: >-
                      Place in the waiting line while the status is
                      WaitingInLine (1 = next to run). Null once the session has
                      started, and for sessions that never waited
                  queue:
                    type:
                      - object
                      - 'null'
                    properties:
                      queueId:
                        type: string
                        description: The ID of the queue the session was enqueued onto
                      name:
                        type: string
                        description: Name of the queue
                      status:
                        type: string
                        enum:
                          - active
                          - paused
                        description: >-
                          Whether the queue dispatches work. A paused queue
                          holds waiting threads until resumed.
                      waitingCount:
                        type: integer
                        description: >-
                          How many of the queue’s sessions are waiting in line
                          to start
                      inProgressCount:
                        type: integer
                        description: How many of the queue’s sessions are running right now
                      oldestWaitingEnqueuedAt:
                        type:
                          - string
                          - 'null'
                        description: >-
                          When the session that has been waiting longest was
                          enqueued, or null when nothing is waiting
                    required:
                      - queueId
                      - name
                      - status
                      - waitingCount
                      - inProgressCount
                      - oldestWaitingEnqueuedAt
                    description: The queue gating the session, if any
                  createdAt:
                    type: string
                    description: When the session was created, as an ISO 8601 timestamp
                  statusLastUpdatedAt:
                    type: string
                    description: >-
                      When the session last changed status, as an ISO 8601
                      timestamp
                required:
                  - sessionId
                  - agentId
                  - status
                  - queuePositionInLine
                  - queue
                  - createdAt
                  - statusLastUpdatedAt
        '400':
          description: Bad request
        '401':
          description: Unauthorized
        '404':
          description: 'The session does not exist. Code: AGENT_SESSION_NOT_FOUND.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: false
                    description: Always false for an error response.
                    example: false
                  error:
                    type: object
                    properties:
                      code:
                        $ref: '#/components/schemas/Schema_57'
                      message:
                        type: string
                        description: Human-readable description of what went wrong.
                        example: >-
                          Agent queue not found: 'agent_queue_123'. Verify the
                          queueId is correct.
                    required:
                      - code
                      - message
                    description: Error details.
                required:
                  - success
                  - error
                description: Error response returned by agent-queue endpoints.
        '500':
          description: Internal server error
      x-codeSamples:
        - lang: cURL
          source: |-
            curl -X POST https://api.kaizenautomation.com/agents/sessions/get \
              -H "Authorization: Bearer YOUR_KAIZEN_API_KEY_HERE" \
              -H "Content-Type: application/json" \
              -d '{
                "sessionId": "YOUR_SESSION_ID_HERE"
              }'
components:
  schemas:
    Schema_57:
      type: string
      enum:
        - AGENT_QUEUES_NOT_ENABLED
        - AGENT_QUEUE_NOT_FOUND
        - QUEUE_AGENT_NOT_FOUND
        - QUEUE_HAS_NO_RESOLVABLE_AGENT
        - AGENT_SESSION_NOT_FOUND
        - AGENT_SESSION_NOT_PAUSABLE
      description: >-
        Machine-readable error code. `AGENT_QUEUES_NOT_ENABLED`: agent queues
        are turned off for your workspace. `AGENT_QUEUE_NOT_FOUND`: the queueId
        does not exist. `QUEUE_AGENT_NOT_FOUND`: the supplied agentId does not
        exist. `QUEUE_HAS_NO_RESOLVABLE_AGENT`: no agentId was supplied and no
        agent could be resolved for the queue. `AGENT_SESSION_NOT_FOUND`: the
        sessionId does not exist. `AGENT_SESSION_NOT_PAUSABLE`: the session has
        already finished, so there is nothing to pause.
      example: AGENT_QUEUE_NOT_FOUND

````