> ## Documentation Index > Fetch the complete documentation index at: https://docs.video2ctx.dev/llms.txt > Use this file to discover all available pages before exploring further. # Read an agent session > Returns the authenticated user’s session metadata and a chronological page of user and assistant messages. The first page contains the newest turns, ordered oldest to newest within the page. Use nextCursor to load older turns. Tool calls, evidence packets, and internal events are not included. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/agent/sessions/{sessionId} openapi: 3.1.0 info: title: video2ctx API version: 1.0.0 license: name: Apache License 2.0 identifier: Apache-2.0 description: >- Consumer-facing contract for the hosted video2ctx API. First-party application and operator routes are documented separately at https://docs.video2ctx.dev/internals/overview. servers: - url: https://api.video2ctx.dev description: Hosted video2ctx API security: [] tags: - name: System description: Service status and machine-readable documentation. - name: Authentication description: Better Auth entry points used by the web application. - name: Providers description: Supported external video providers and their capabilities. - name: Discovery description: Search, browse, and trend research. - name: Videos description: Video metadata and evidence. - name: Channels description: Channel inspection. - name: Playlists description: Playlist inspection. - name: Projects description: Private research projects and saved material. - name: Research description: Imports, jobs, cited answers, comparisons, and reports. - name: Agents description: >- Durable agent runs and results. Feature-flagged; access is restricted to verified, allowlisted tester accounts during the initial rollout. - name: Exports description: Project export creation and download. - name: Monitoring description: Monitors, notifications, and digest preferences. - name: Billing description: Plan, credit, and subscription status. - name: Account description: Account lifecycle operations. paths: /v1/agent/sessions/{sessionId}: get: tags: - Agents summary: Read an agent session description: >- Returns the authenticated user’s session metadata and a chronological page of user and assistant messages. The first page contains the newest turns, ordered oldest to newest within the page. Use nextCursor to load older turns. Tool calls, evidence packets, and internal events are not included. operationId: getAgentSession parameters: - name: sessionId in: path required: true description: Session UUID returned by agent admission. schema: type: string minLength: 1 - name: limit in: query required: false description: >- Maximum turns to return. Each turn produces one user message and one assistant message. schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query required: false description: Opaque cursor for loading turns older than the current page. schema: type: string maxLength: 500 responses: '200': description: The restored agent session. content: application/json: schema: $ref: '#/components/schemas/AgentSessionDetail' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '422': $ref: '#/components/responses/ValidationError' '500': $ref: '#/components/responses/ServerError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - bearerApiKey: [] - sessionCookie: [] - cliSession: [] - apiKey: [] - demoUser: [] components: schemas: AgentSessionDetail: allOf: - $ref: '#/components/schemas/AgentSession' - type: object required: - messages - nextCursor properties: messages: type: array maxItems: 200 items: $ref: '#/components/schemas/AgentConversationMessage' nextCursor: type: - string - 'null' AgentSession: type: object required: - sessionId - title - latestMessagePreview - lastRunId - runCount - createdAt - updatedAt properties: sessionId: type: string format: uuid title: type: string maxLength: 80 latestMessagePreview: type: string maxLength: 240 lastRunId: type: string format: uuid runCount: type: integer minimum: 1 createdAt: type: integer minimum: 0 description: Unix timestamp in milliseconds. updatedAt: type: integer minimum: 0 description: Unix timestamp in milliseconds. AgentConversationMessage: type: object required: - messageId - runId - conversationTurn - parentMessageId - role - status - content - createdAt - updatedAt properties: messageId: type: string format: uuid runId: type: string format: uuid conversationTurn: type: integer minimum: 1 parentMessageId: type: - string - 'null' format: uuid description: The preceding message in this conversation branch. role: type: string enum: - user - assistant status: type: string enum: - pending - running - completed - failed - cancelled content: type: string description: Empty for an assistant message whose run has not produced an answer. createdAt: type: integer minimum: 0 description: Unix timestamp in milliseconds. updatedAt: type: integer minimum: 0 description: Unix timestamp in milliseconds. Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string example: QUERY_REQUIRED message: type: string details: {} requestId: type: string responses: Unauthorized: description: Authentication is required. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: The caller is not allowed to perform this operation. content: application/json: schema: $ref: '#/components/schemas/Error' NotFound: description: The requested resource was not found. content: application/json: schema: $ref: '#/components/schemas/Error' ValidationError: description: The request failed validation. content: application/json: schema: $ref: '#/components/schemas/Error' ServerError: description: An unexpected server error occurred. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: An upstream AI or YouTube service is unavailable. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: bearerApiKey: type: http scheme: bearer bearerFormat: API key description: >- Permanent personal API key created in the dashboard. Example: curl -H "Authorization: Bearer aty_…" https://your-host/v1/projects sessionCookie: type: apiKey in: cookie name: better-auth.session_token description: >- Better Auth session cookie. A production deployment may use the secure-prefixed cookie name; same-origin browser requests send it automatically. cliSession: type: http scheme: bearer bearerFormat: CLI session description: >- Short-lived, revocable session issued by the video2ctx device authorization flow. The official CLI stores and sends this value; never paste it into prompts or logs. apiKey: type: apiKey in: header name: X-API-Key description: >- Legacy-compatible header for a permanent personal API key. Prefer Authorization: Bearer aty_…. demoUser: type: apiKey in: header name: X-Demo-User description: >- Local development only. Any stable value selects an isolated demo account. Rejected in production. ````