Skip to content

Add docs for agent session retrieval #436

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+337 −0
Open

Add docs for agent session retrieval #436

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions deployment/pipecat-cloud/rest-reference/endpoint/agent-get-sessions.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
title: "Retrieve Agent Sessions"
description: "Get sessions for an agent with filtering and pagination options."
openapi: "GET /agents/{agentName}/sessions"
---
331 changes: 331 additions & 0 deletions deployment/pipecat-cloud/rest-reference/openapi-agent-get-sessions.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,331 @@
{
"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 (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"
}
}
}
}
}
}
}
},
"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": []
}
]
}
1 change: 1 addition & 0 deletions docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -593,6 +593,7 @@
"deployment/pipecat-cloud/rest-reference/endpoint/start",
"deployment/pipecat-cloud/rest-reference/endpoint/stop",
"deployment/pipecat-cloud/rest-reference/endpoint/agent-get-logs",
"deployment/pipecat-cloud/rest-reference/endpoint/agent-get-sessions",
"deployment/pipecat-cloud/rest-reference/endpoint/agent-list-one",
"deployment/pipecat-cloud/rest-reference/endpoint/agent-list-all",
"deployment/pipecat-cloud/rest-reference/endpoint/agent-delete"
Expand Down