{
  "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"
    }
  ],
  "paths": {
    "/agents/{agentName}/sessions": {
      "get": {
        "summary": "Get agent sessions",
        "description": "Retrieves sessions for the specified agent with optional filtering and pagination.",
        "operationId": "getSessions",
        "security": [
          {
            "PrivateKeyAuth": []
          }
        ],
        "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](/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"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PrivateKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Authentication requires a Pipecat Cloud Private API token.\n\nGenerate a Private API key from your Dashboard (Settings > API Keys > Private > Create key) and include it as a Bearer token in the Authorization header."
      }
    },
    "schemas": {
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "description": "Error message"
          },
          "code": {
            "type": "string",
            "description": "Error code"
          }
        }
      }
    }
  },
  "security": [
    {
      "PrivateKeyAuth": []
    }
  ]
}