# Source: https://docs.pipecat.ai/deployment/pipecat-cloud/rest-reference/endpoint/agent-get-sessions.md

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

# Retrieve Agent Sessions

> Get sessions for an agent with filtering and pagination options.



## OpenAPI

````yaml GET /agents/{agentName}/sessions
openapi: 3.0.0
info:
  title: Pipecat Cloud
  version: 1.0.0
  description: Private API for Pipecat Cloud agent management
servers:
  - url: https://api.pipecat.daily.co/v1
    description: API server
security:
  - PrivateKeyAuth: []
paths:
  /agents/{agentName}/sessions:
    get:
      summary: Get agent sessions
      description: >-
        Retrieves sessions for the specified agent with optional filtering and
        pagination.
      operationId: getSessions
      parameters:
        - name: agentName
          in: path
          required: true
          description: Name of the agent to retrieve sessions for
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Maximum number of sessions to return
          schema:
            type: integer
            default: 10
        - name: offset
          in: query
          required: false
          description: Number of sessions to skip
          schema:
            type: integer
            default: 0
        - name: deploymentId
          in: query
          required: false
          description: Filter sessions to a specific deployment ID
          schema:
            type: string
        - name: startTime
          in: query
          required: false
          description: Filter sessions to those after this Unix timestamp
          schema:
            type: integer
        - name: endTime
          in: query
          required: false
          description: Filter sessions to those before this Unix timestamp
          schema:
            type: integer
        - name: status
          in: query
          required: false
          description: Filter sessions to those with this status
          schema:
            type: string
            enum:
              - active
              - ended
              - all
            default: all
        - name: startType
          in: query
          required: false
          description: Filter sessions to those with this start type
          schema:
            type: string
            enum:
              - cold
              - warm
              - all
            default: all
        - name: startTimeMin
          in: query
          required: false
          description: >-
            Filter sessions to those whose start times are greater than this
            value in seconds
          schema:
            type: integer
            default: 0
        - name: startTimeMax
          in: query
          required: false
          description: >-
            Filter sessions to those whose start times are less than this value
            in seconds
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: Agent sessions retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_count:
                    type: integer
                    description: Total number of sessions matching the parameters
                  sessions:
                    type: array
                    description: List of sessions
                    items:
                      type: object
                      properties:
                        sessionId:
                          type: string
                          description: ID of the session
                        serviceId:
                          type: string
                          description: ID of the service for this session
                        organizationId:
                          type: string
                          description: >-
                            ID of the organization that this session is
                            associated with
                        deploymentId:
                          type: string
                          description: >-
                            ID of the deployment that this session is associated
                            with
                        endedAt:
                          type: string
                          format: date-time
                          description: Timestamp when the log was generated
                        botStartSeconds:
                          type: integer
                          description: >-
                            Number of seconds between bot start request and bot
                            start
                          nullable: true
                        coldStart:
                          type: boolean
                          description: >-
                            Whether the bot start was a cold start (see
                            https://docs.pipecat.ai/deployment/pipecat-cloud/fundamentals/scaling#cold-starts)
                          nullable: true
                        completionStatus:
                          type: string
                          description: >-
                            The completion status of the session. This can be an
                            http return code or a string like `HTTP_COMPLETED`,
                            `HTTP_ERROR`, `WS_CONNECTION_CLOSED`, among others
                          nullable: true
                        createdAt:
                          type: string
                          format: date-time
                          description: Timestamp when the session was created
                        updatedAt:
                          type: string
                          format: date-time
                          description: Timestamp when the session was last updated
              example:
                total_count: 330
                sessions:
                  - sessionId: 800d444a-e67e-4686-afb3-b0de509cccb3
                    serviceId: b900ae4a-f710-4ef1-95d8-c5f5b2789da9
                    organizationId: cc71b52d-4271-46c9-87be-cac600fd821a
                    deploymentId: 81f4da55-106d-401f-b069-a1f1992f871a
                    endedAt: '2025-10-22T08:39:26.000Z'
                    botStartSeconds: 0
                    coldStart: false
                    completionStatus: HTTP_COMPLETED
                    createdAt: '2025-10-22T08:39:26.000Z'
                    updatedAt: '2025-10-22T08:39:26.000Z'
                  - sessionId: 803349cc-2ae0-437a-9a72-408817299e43
                    serviceId: b900ae4a-f710-4ef1-95d8-c5f5b2789da9
                    organizationId: cc71b52d-4271-46c9-87be-cac600fd821a
                    deploymentId: 81f4da55-106d-401f-b069-a1f1992f871a
                    endedAt: '2025-10-22T08:38:09.000Z'
                    botStartSeconds: 2
                    coldStart: true
                    completionStatus: HTTP_COMPLETED
                    createdAt: '2025-10-22T08:38:09.000Z'
                    updatedAt: '2025-10-22T08:38:09.000Z'
                  - sessionId: 44003e83-b679-46ef-88ec-18e9ea9dd81d
                    serviceId: b900ae4a-f710-4ef1-95d8-c5f5b2789da9
                    organizationId: cc71b52d-4271-46c9-87be-cac600fd821a
                    deploymentId: f76bae42-5ce8-4ae3-8a75-0349bfd7ec63
                    endedAt: '2025-10-21T08:17:47.000Z'
                    botStartSeconds: 0
                    coldStart: false
                    completionStatus: HTTP_ERROR
                    createdAt: '2025-10-21T08:17:22.000Z'
                    updatedAt: '2025-10-21T08:17:38.000Z'
        '400':
          description: Invalid query parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: Invalid parameters
                err:
                  issues:
                    - received: bad_value
                      code: invalid_enum_value
                      options:
                        - active
                        - ended
                        - all
                      path:
                        - status
                      message: >-
                        Invalid enum value. Expected 'active' | 'ended' | 'all',
                        received 'bad_value'
                  name: ZodError
                code: '400'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  API endpoint not found / agent deployment not found /
                  Organization not found
                code: '404'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Internal server error. Please check logs for more information
                  or contact support.
                code: '500'
      security:
        - PrivateKeyAuth: []
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
  securitySchemes:
    PrivateKeyAuth:
      type: http
      scheme: bearer
      description: >-
        Authentication requires a Pipecat Cloud Private API token.


        Generate a Private API key from your Dashboard (Settings > API Keys >
        Private > Create key) and include it as a Bearer token in the
        Authorization header.

````