> ## Documentation Index > Fetch the complete documentation index at: https://docs.actx0.com/llms.txt > Use this file to discover all available pages before exploring further. # List Sessions > List agent sessions. Optionally filter with `id` and/or labels. Identify sessions with the `id` query param and/or arbitrary label query params (every query key except `id`, `limit`, and `offset` becomes a label). Example: `?id=ticket-4821&userId=alice&channel=web`. ## OpenAPI ````yaml /openapi.yaml get /workspaces/{workspaceId}/agents/{agentId}/sessions openapi: 3.1.0 info: title: Actx0 API version: 1.0.0 description: >- REST API for Actx0 workspaces, access keys, agents, sessions, messages, memories, prompts, and knowledge documents. Authenticate with `X-Access-Key` (workspace), `X-API-Key` (user), or a dashboard session. servers: - url: https://app.actx0.com/api/v1 description: Actx0 cloud security: [] tags: - name: Me description: Inspect the authenticated access key or API key - name: API Keys description: User API keys for X-API-Key auth - name: Workspaces description: Team workspaces - name: Access Keys description: Scoped workspace keys for agents and SDKs - name: Agents description: Agents inside a workspace - name: Sessions description: Agent conversation sessions - name: Messages description: Session messages and semantic search - name: Memories description: Session memories, search, batch, and regenerate - name: Prompts description: Versioned prompts - name: Knowledge description: Document upload and semantic search paths: /workspaces/{workspaceId}/agents/{agentId}/sessions: get: tags: - Sessions summary: List Sessions description: >- List agent sessions. Optionally filter with `id` and/or labels. Identify sessions with the `id` query param and/or arbitrary label query params (every query key except `id`, `limit`, and `offset` becomes a label). Example: `?id=ticket-4821&userId=alice&channel=web`. operationId: listSessions parameters: - $ref: '#/components/parameters/WorkspaceId' - $ref: '#/components/parameters/AgentId' - $ref: '#/components/parameters/SessionExternalId' - $ref: '#/components/parameters/Limit' - $ref: '#/components/parameters/Offset' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SessionList' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - AccessKeyAuth: [] - ApiKeyAuth: [] x-codeSamples: - lang: curl label: curl / acli source: > curl -X GET 'https://app.actx0.com/api/v1/workspaces//agents//sessions' \ -H "X-Access-Key: YOUR_ACCESS_KEY" \ -H "Accept: application/json" # --- # acli export ACTX0_ACCESS_KEY="YOUR_ACCESS_KEY" export ACTX0_WORKSPACE_ID="YOUR_WORKSPACE_ID" acli session list --agent-id AGENT_ID - lang: python label: pctx0 source: | from pctx0 import Pctx0Client client = Pctx0Client( access_key="YOUR_ACCESS_KEY", workspace_id="YOUR_WORKSPACE_ID", ) sessions = client.session.list("AGENT_ID", limit=50, offset=0) - lang: javascript label: nctx0 source: > import { Nctx0Client } from "@actx0/nctx0"; const client = new Nctx0Client({ accessKey: "YOUR_ACCESS_KEY", workspaceId: "YOUR_WORKSPACE_ID", }); const sessions = await client.session.list("AGENT_ID", { limit: 50, offset: 0 }); - lang: go label: gtcx0 source: "package main\n\nimport (\n\t\"context\"\n\n\t\"github.com/Actx0/Gctx0\"\n)\n\nfunc main() {\n\tclient := gctx0.NewClient(\n\t\tgctx0.WithAccessKey(\"YOUR_ACCESS_KEY\"),\n\t\tgctx0.WithWorkspaceId(\"YOUR_WORKSPACE_ID\"),\n\t)\n\tdefer client.Close()\n\tctx := context.Background()\n\tsessions, err := client.Session.List(ctx, \"AGENT_ID\", gctx0.SessionLookup{}, 50, 0)\n\t_ = sessions\n\t_ = err\n}\n" components: parameters: WorkspaceId: name: workspaceId in: path required: true schema: type: string format: uuid example: 11111111-1111-1111-1111-111111111111 AgentId: name: agentId in: path required: true schema: type: string format: uuid example: 22222222-2222-2222-2222-222222222222 SessionExternalId: name: id in: query required: false schema: type: string description: External session id. Provide id and/or arbitrary label query params. example: ticket-4821 Limit: name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 50 description: Page size. Defaults to 50, max 100. Offset: name: offset in: query required: false schema: type: integer minimum: 0 default: 0 description: Number of items to skip. schemas: SessionList: type: object required: - sessions - _meta properties: sessions: type: array items: $ref: '#/components/schemas/Session' _meta: $ref: '#/components/schemas/PaginationMeta' Error: type: object required: - errorMessage properties: errorMessage: type: string example: Name is required Session: type: object required: - id - externalId - workspaceId - agentId - status - createdAt - updatedAt properties: id: type: string format: uuid description: Internal session UUID used in message and memory paths. example: 33333333-3333-3333-3333-333333333333 externalId: type: string description: Client-facing session id from the id query param (or generated). example: ticket-4821 workspaceId: type: string format: uuid example: 11111111-1111-1111-1111-111111111111 agentId: type: string format: uuid example: 22222222-2222-2222-2222-222222222222 title: type: string example: 'Ticket #4821' status: type: string example: active labels: type: object additionalProperties: type: string example: userId: alice channel: web meta: {} lastActivityAt: type: string format: date-time example: '2026-07-01T12:00:00Z' createdAt: type: string format: date-time example: '2026-07-01T12:00:00Z' updatedAt: type: string format: date-time example: '2026-07-01T12:00:00Z' PaginationMeta: type: object required: - limit - offset - total properties: limit: type: integer example: 50 offset: type: integer example: 0 total: type: integer example: 12 securitySchemes: AccessKeyAuth: type: apiKey in: header name: X-Access-Key description: Workspace access key for agent/runtime integrations. ApiKeyAuth: type: apiKey in: header name: X-API-Key description: User API key for management and automation. ````