Skip to content

Commit c024723

Browse files
markbackmanmarkbackman
authored
Merge pull request #436 from pipecat-ai/ss/agent-sessions-endpoint
Add docs for agent session retrieval
2 parents de46862 + 14761cd commit c024723

File tree

3 files changed

+337
-0
lines changed

3 files changed

+337
-0
lines changed

‎deployment/pipecat-cloud/rest-reference/endpoint/agent-get-sessions.mdx‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Retrieve Agent Sessions"
3+
description: "Get sessions for an agent with filtering and pagination options."
4+
openapi: "GET /agents/{agentName}/sessions"
5+
---

‎deployment/pipecat-cloud/rest-reference/openapi-agent-get-sessions.json‎

Lines changed: 331 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,331 @@
1+
{
2+
"openapi": "3.0.0",
3+
"info": {
4+
"title": "Pipecat Cloud",
5+
"version": "1.0.0",
6+
"description": "Private API for Pipecat Cloud agent management"
7+
},
8+
"servers": [
9+
{
10+
"url": "https://api.pipecat.daily.co/v1",
11+
"description": "API server"
12+
}
13+
],
14+
"paths": {
15+
"/agents/{agentName}/sessions": {
16+
"get": {
17+
"summary": "Get agent sessions",
18+
"description": "Retrieves sessions for the specified agent with optional filtering and pagination.",
19+
"operationId": "getSessions",
20+
"security": [
21+
{
22+
"PrivateKeyAuth": []
23+
}
24+
],
25+
"parameters": [
26+
{
27+
"name": "agentName",
28+
"in": "path",
29+
"required": true,
30+
"description": "Name of the agent to retrieve sessions for",
31+
"schema": {
32+
"type": "string"
33+
}
34+
},
35+
{
36+
"name": "limit",
37+
"in": "query",
38+
"required": false,
39+
"description": "Maximum number of sessions to return",
40+
"schema": {
41+
"type": "integer",
42+
"default": 10
43+
}
44+
},
45+
{
46+
"name": "offset",
47+
"in": "query",
48+
"required": false,
49+
"description": "Number of sessions to skip",
50+
"schema": {
51+
"type": "integer",
52+
"default": 0
53+
}
54+
},
55+
{
56+
"name": "deploymentId",
57+
"in": "query",
58+
"required": false,
59+
"description": "Filter sessions to a specific deployment ID",
60+
"schema": {
61+
"type": "string"
62+
}
63+
},
64+
{
65+
"name": "startTime",
66+
"in": "query",
67+
"required": false,
68+
"description": "Filter sessions to those after this Unix timestamp",
69+
"schema": {
70+
"type": "integer"
71+
}
72+
},
73+
{
74+
"name": "endTime",
75+
"in": "query",
76+
"required": false,
77+
"description": "Filter sessions to those before this Unix timestamp",
78+
"schema": {
79+
"type": "integer"
80+
}
81+
},
82+
{
83+
"name": "status",
84+
"in": "query",
85+
"required": false,
86+
"description": "Filter sessions to those with this status",
87+
"schema": {
88+
"type": "string",
89+
"enum": ["active", "ended", "all"],
90+
"default": "all"
91+
}
92+
},
93+
{
94+
"name": "startType",
95+
"in": "query",
96+
"required": false,
97+
"description": "Filter sessions to those with this start type",
98+
"schema": {
99+
"type": "string",
100+
"enum": ["cold", "warm", "all"],
101+
"default": "all"
102+
}
103+
},
104+
{
105+
"name": "startTimeMin",
106+
"in": "query",
107+
"required": false,
108+
"description": "Filter sessions to those whose start times are greater than this value in seconds",
109+
"schema": {
110+
"type": "integer",
111+
"default": 0
112+
}
113+
},
114+
{
115+
"name": "startTimeMax",
116+
"in": "query",
117+
"required": false,
118+
"description": "Filter sessions to those whose start times are less than this value in seconds",
119+
"schema": {
120+
"type": "integer",
121+
"default": 0
122+
}
123+
},
124+
],
125+
"responses": {
126+
"200": {
127+
"description": "Agent sessions retrieved successfully",
128+
"content": {
129+
"application/json": {
130+
"schema": {
131+
"type": "object",
132+
"properties": {
133+
"total_count": {
134+
"type": "integer",
135+
"description": "Total number of sessions matching the parameters"
136+
},
137+
"sessions": {
138+
"type": "array",
139+
"description": "List of sessions",
140+
"items": {
141+
"type": "object",
142+
"properties": {
143+
"sessionId": {
144+
"type": "string",
145+
"description": "ID of the session"
146+
},
147+
"serviceId": {
148+
"type": "string",
149+
"description": "ID of the service for this session"
150+
},
151+
"organizationId": {
152+
"type": "string",
153+
"description": "ID of the organization that this session is associated with"
154+
},
155+
"deploymentId": {
156+
"type": "string",
157+
"description": "ID of the deployment that this session is associated with",
158+
},
159+
"endedAt": {
160+
"type": "string",
161+
"format": "date-time",
162+
"description": "Timestamp when the log was generated"
163+
},
164+
"botStartSeconds": {
165+
"type": "integer",
166+
"description": "Number of seconds between bot start request and bot start",
167+
"nullable": true
168+
},
169+
"coldStart": {
170+
"type": "boolean",
171+
"description": "Whether the bot start was a cold start (see https://docs.pipecat.ai/deployment/pipecat-cloud/fundamentals/scaling#cold-starts)",
172+
"nullable": true
173+
},
174+
"completionStatus": {
175+
"type": "string",
176+
"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",
177+
"nullable": true
178+
},
179+
"createdAt": {
180+
"type": "string",
181+
"format": "date-time",
182+
"description": "Timestamp when the session was created"
183+
},
184+
"updatedAt": {
185+
"type": "string",
186+
"format": "date-time",
187+
"description": "Timestamp when the session was last updated"
188+
},
189+
}
190+
}
191+
}
192+
}
193+
},
194+
"example": {
195+
"total_count": 330,
196+
"sessions": [
197+
{
198+
"sessionId": "800d444a-e67e-4686-afb3-b0de509cccb3",
199+
"serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9",
200+
"organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a",
201+
"deploymentId": "81f4da55-106d-401f-b069-a1f1992f871a",
202+
"endedAt": "2025-10-22T08:39:26.000Z",
203+
"botStartSeconds": 0,
204+
"coldStart": false,
205+
"completionStatus": "HTTP_COMPLETED",
206+
"createdAt": "2025-10-22T08:39:26.000Z",
207+
"updatedAt": "2025-10-22T08:39:26.000Z"
208+
},
209+
{
210+
"sessionId": "803349cc-2ae0-437a-9a72-408817299e43",
211+
"serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9",
212+
"organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a",
213+
"deploymentId": "81f4da55-106d-401f-b069-a1f1992f871a",
214+
"endedAt": "2025-10-22T08:38:09.000Z",
215+
"botStartSeconds": 2,
216+
"coldStart": true,
217+
"completionStatus": "HTTP_COMPLETED",
218+
"createdAt": "2025-10-22T08:38:09.000Z",
219+
"updatedAt": "2025-10-22T08:38:09.000Z"
220+
},
221+
{
222+
"sessionId": "44003e83-b679-46ef-88ec-18e9ea9dd81d",
223+
"serviceId": "b900ae4a-f710-4ef1-95d8-c5f5b2789da9",
224+
"organizationId": "cc71b52d-4271-46c9-87be-cac600fd821a",
225+
"deploymentId": "f76bae42-5ce8-4ae3-8a75-0349bfd7ec63",
226+
"endedAt": "2025-10-21T08:17:47.000Z",
227+
"botStartSeconds": 0,
228+
"coldStart": false,
229+
"completionStatus": "HTTP_ERROR",
230+
"createdAt": "2025-10-21T08:17:22.000Z",
231+
"updatedAt": "2025-10-21T08:17:38.000Z"
232+
}
233+
]
234+
}
235+
}
236+
}
237+
},
238+
"400": {
239+
"description": "Invalid query parameters",
240+
"content": {
241+
"application/json": {
242+
"schema": {
243+
"$ref": "#/components/schemas/ErrorResponse"
244+
},
245+
"example": {
246+
"error": "Invalid parameters",
247+
"err": {
248+
"issues": [
249+
{
250+
"received": "bad_value",
251+
"code": "invalid_enum_value",
252+
"options": [
253+
"active",
254+
"ended",
255+
"all"
256+
],
257+
"path": [
258+
"status"
259+
],
260+
"message": "Invalid enum value. Expected 'active' | 'ended' | 'all', received 'bad_value'"
261+
}
262+
],
263+
"name": "ZodError"
264+
},
265+
"code": "400"
266+
}
267+
}
268+
}
269+
},
270+
"404": {
271+
"description": "Agent not found",
272+
"content": {
273+
"application/json": {
274+
"schema": {
275+
"$ref": "#/components/schemas/ErrorResponse"
276+
},
277+
"example": {
278+
"error": "API endpoint not found / agent deployment not found / Organization not found",
279+
"code": "404"
280+
}
281+
}
282+
}
283+
},
284+
"500": {
285+
"description": "Internal server error",
286+
"content": {
287+
"application/json": {
288+
"schema": {
289+
"$ref": "#/components/schemas/ErrorResponse"
290+
},
291+
"example": {
292+
"error": "Internal server error. Please check logs for more information or contact support.",
293+
"code": "500"
294+
}
295+
}
296+
}
297+
}
298+
}
299+
}
300+
}
301+
},
302+
"components": {
303+
"securitySchemes": {
304+
"PrivateKeyAuth": {
305+
"type": "http",
306+
"scheme": "bearer",
307+
"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."
308+
}
309+
},
310+
"schemas": {
311+
"ErrorResponse": {
312+
"type": "object",
313+
"properties": {
314+
"error": {
315+
"type": "string",
316+
"description": "Error message"
317+
},
318+
"code": {
319+
"type": "string",
320+
"description": "Error code"
321+
}
322+
}
323+
}
324+
}
325+
},
326+
"security": [
327+
{
328+
"PrivateKeyAuth": []
329+
}
330+
]
331+
}

‎docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -595,6 +595,7 @@
595595
"deployment/pipecat-cloud/rest-reference/endpoint/start",
596596
"deployment/pipecat-cloud/rest-reference/endpoint/stop",
597597
"deployment/pipecat-cloud/rest-reference/endpoint/agent-get-logs",
598+
"deployment/pipecat-cloud/rest-reference/endpoint/agent-get-sessions",
598599
"deployment/pipecat-cloud/rest-reference/endpoint/agent-list-one",
599600
"deployment/pipecat-cloud/rest-reference/endpoint/agent-list-all",
600601
"deployment/pipecat-cloud/rest-reference/endpoint/agent-delete"

0 commit comments

Comments
 (0)