> ## 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.

# Pause session

> Pauses a session, whether it has started or not. A session that is running stops where it is and hands back the slot it was holding, so the next session in line can start; a session still waiting in line leaves the line. Either way it ends up Paused, and can be picked back up by sending it another message. Pausing a session that is already paused does nothing.



## OpenAPI

````yaml post /agents/sessions/pause
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/pause:
    post:
      tags:
        - Agents
      summary: Pause session
      description: >-
        Pauses a session, whether it has started or not. A session that is
        running stops where it is and hands back the slot it was holding, so the
        next session in line can start; a session still waiting in line leaves
        the line. Either way it ends up Paused, and can be picked back up by
        sending it another message. Pausing a session that is already paused
        does nothing.
      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 is paused
          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
                  status:
                    type: string
                    enum:
                      - Pending
                      - InProgress
                      - Completed
                      - Failed
                      - Paused
                      - WaitingInLine
                      - Sleeping
                    description: Lifecycle status of the session after the pause
                    example: Paused
                  queueId:
                    type:
                      - string
                      - 'null'
                    description: >-
                      The ID of the queue the session was on, if it was enqueued
                      onto one
                  pausedSessionCount:
                    type: integer
                    description: >-
                      How many sessions were paused: the session itself plus any
                      child sessions it started
                required:
                  - sessionId
                  - status
                  - queueId
                  - pausedSessionCount
        '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.
        '409':
          description: >-
            The session has already finished, so there is nothing to pause.
            Code: AGENT_SESSION_NOT_PAUSABLE.
          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/pause
            \
              -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

````