--- title: "Sessions — AVCodex Docs" description: "Sessions — AVCodex documentation for AV integrators, programmers, and ops teams." lang: en json-ld: --- [](/) Solutions [Pricing](/pricing)[The Signal](/blog)[Resources](/resources) Learn [Free AI Assessment](/scorecard)[Get Started →](/pricing) [Documentation Home](/docs) Guides Custom Actions Pro Actions API Builder API - [Overview](/docs/builder-api/overview) - [Sessions](/docs/builder-api/sessions) - [Consumers](/docs/builder-api/consumers) - [Feedback](/docs/builder-api/feedback) - [Tags](/docs/builder-api/tags) - [Knowledge Sources](/docs/builder-api/knowledge-sources) - [Memories](/docs/builder-api/memories) - [Analytics](/docs/builder-api/analytics) Agentic Commerce (ACP) Integrations [Docs](/docs)/ Builder API / Builder API # Sessions Last updated · MAR 2026 · [Read as Markdown](/docs/builder-api/sessions.md) Sessions represent individual chat conversations with your agent. Each session contains messages exchanged between a consumer (a tech, a programmer, an end-client) and your AI agent. ## [List sessions# ](#list-sessions) code ``` GET /api/v1/apps/{appId}/sessions ``` Returns a paginated list of chat sessions, newest first. ### [Query parameters# ](#query-parameters) Parameter Type Default Description `limit` integer 25 Results per page (1-100). `cursor` string \- Pagination cursor from a previous response. `source` string \- Filter by channel. `consumer_id` UUID \- Filter by consumer. `started_after` ISO 8601 \- Sessions started after this date. `started_before` ISO 8601 \- Sessions started before this date. `search` string \- Case-insensitive substring search on session titles (max 200 chars). **Source values:** `APP`, `API`, `WHATSAPP`, `SLACK`, `EMAIL`, `VOICE`, `WIDGET`, `ACP`. ### [Example# ](#example) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?limit=10&source=APP" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### [Response# ](#response) json ``` { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consumer": { "email": "jane@integrator.com", "name": "Jane Smith" }, "title": "Boardroom 4 commissioning Q&A", "source": "APP", "mode": "default", "is_bookmarked": false, "is_multiplayer": false, "message_count": 12, "started_at": "2025-06-15T14:30:00Z", "ended_at": "2025-06-15T14:45:00Z", "last_activity_at": "2025-06-15T14:45:00Z" } ], "pagination": { "has_more": true, "next_cursor": "eyJpZCI6IjU1MGU4NDAw...", "limit": 10 } } ``` ### [Filtering by date range# ](#filtering-by-date-range) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?started_after=2025-06-01T00:00:00Z&started_before=2025-06-30T23:59:59Z" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### [Filtering by consumer# ](#filtering-by-consumer) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions?consumer_id=7c9e6679-7425-40de-944b-e07fc1f90ae7" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` * * * ## [Get session# ](#get-session) code ``` GET /api/v1/apps/{appId}/sessions/{sessionId} ``` Returns a single session by ID. ### [Example# ](#example) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### [Response# ](#response) json ``` { "data": { "id": "550e8400-e29b-41d4-a716-446655440000", "consumer_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "consumer": { "email": "jane@integrator.com", "name": "Jane Smith" }, "title": "Boardroom 4 commissioning Q&A", "source": "APP", "mode": "default", "is_bookmarked": false, "is_multiplayer": false, "message_count": 12, "started_at": "2025-06-15T14:30:00Z", "ended_at": "2025-06-15T14:45:00Z", "last_activity_at": "2025-06-15T14:45:00Z" } } ``` ### [Error: session not found (404)# ](#error-session-not-found-404) json ``` { "error": { "code": "not_found", "message": "Session not found" } } ``` * * * ## [List session messages# ](#list-session-messages) code ``` GET /api/v1/apps/{appId}/sessions/{sessionId}/messages ``` Returns the messages in a session, ordered chronologically. ### [Query parameters# ](#query-parameters) Parameter Type Default Description `limit` integer 25 Results per page (1-100). `cursor` string \- Pagination cursor from a previous response. `role` string \- Filter by role: `user`, `assistant`, `system`, or `tool`. `created_after` ISO 8601 \- Messages created after this date. `created_before` ISO 8601 \- Messages created before this date. `include` string \- Comma-separated list of extra fields to include. **Include values** - `tool_details` - adds `tool_calls` and `tool_results` fields to each message. Arrays when the message invoked tools, `null` when it did not. ### [Example# ](#example) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/550e8400-e29b-41d4-a716-446655440000/messages?limit=50" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` ### [Response# ](#response) json ``` { "data": [ { "id": "msg-001", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "user", "content": "How do I get the Q-SYS Core back online after a power loss?", "model": null, "token_count": 42, "latency_ms": null, "audio_url": null, "audio_duration_ms": null, "tags": [], "feedback": null, "created_at": "2025-06-15T14:30:00Z" }, { "id": "msg-002", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "assistant", "content": "Here's the recovery procedure for the Q-SYS Core...", "model": "gpt-4.1", "token_count": 150, "latency_ms": 1200, "audio_url": null, "audio_duration_ms": null, "tags": [{ "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "qsys", "color": "#3b82f6" }], "feedback": null, "created_at": "2025-06-15T14:30:05Z" } ], "pagination": { "has_more": false, "next_cursor": null, "limit": 50 } } ``` ### [Response fields# ](#response-fields) Field Type Description `id` string Unique message identifier. `session_id` UUID The session this message belongs to. `role` string `user`, `assistant`, `system`, or `tool`. `content` string Message text content. `model` string or null LLM model used (null for user messages). `token_count` integer or null Token count for this message. `latency_ms` integer or null Response latency in milliseconds. `audio_url` string or null URL to audio recording, if applicable. `audio_duration_ms` integer or null Audio duration in milliseconds. `tags` array of objects Tags applied to this message. Each object has `id` (UUID), `name` (string), and `color` (hex string). `feedback` object or null Feedback on this message, if any. `created_at` ISO 8601 When the message was created. ### [With tool details# ](#with-tool-details) bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?include=tool_details" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` json ``` { "data": [ { "id": "msg-003", "session_id": "550e8400-e29b-41d4-a716-446655440000", "role": "assistant", "content": "Let me look that up for you.", "model": "gpt-4.1", "token_count": 180, "latency_ms": 2400, "audio_url": null, "audio_duration_ms": null, "tags": [], "feedback": null, "created_at": "2025-06-15T14:31:00Z", "tool_calls": [ { "tool_name": "search_knowledge", "status": "completed" } ], "tool_results": [ { "tool_name": "search_knowledge", "result": "..." } ] } ], "pagination": { "has_more": false, "next_cursor": null, "limit": 25 } } ``` ### [Filtering by role# ](#filtering-by-role) To retrieve only user messages (useful for extracting tech questions): bash ``` curl "https://app.avcodex.com/api/v1/apps/YOUR_APP_ID/sessions/SESSION_ID/messages?role=user" \ -H "Authorization: Bearer avcodex_YOUR_API_KEY" ``` \*AVCodex · Your AV expertise. Amplified by AI.\* Was this helpful? [Edit this page →](#) [ Previous Overview ](/docs/builder-api/overview)[ Next Consumers ](/docs/builder-api/consumers) On this page - [List sessions](#list-sessions) - [Query parameters](#query-parameters) - [Example](#example) - [Response](#response) - [Filtering by date range](#filtering-by-date-range) - [Filtering by consumer](#filtering-by-consumer) - [Get session](#get-session) - [Example](#example) - [Response](#response) - [Error: session not found (404)](#error-session-not-found-404) - [List session messages](#list-session-messages) - [Query parameters](#query-parameters) - [Example](#example) - [Response](#response) - [Response fields](#response-fields) - [With tool details](#with-tool-details) - [Filtering by role](#filtering-by-role) [](/) The AI platform built exclusively for professional AV. Build, deploy, and sell AI tools that understand your industry. ### Platform - What You Can Build - Templates - [Pricing](/pricing) ### Services - [Done-For-You](/pricing) - [Academy](/academy) - [Contact](/contact) ### Company - About - [The Signal](/blog) - [Docs](/docs) - [LinkedIn](#) © 2026 AVCodex. A Future Ready Holdings Inc. product. SOC 2 Type II Certified · HIPAA Compliant