> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agntix.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# List Sessions

> Returns a paginated list of chat sessions, ordered most-recent first.

<Note>
  Every endpoint on this page requires either a Clerk-issued JWT (`Authorization: Bearer <token>`) or
  an organization API key (`x-api-key: pk_…`). Anonymous calls return `401 Unauthorized`. See
  [Authentication](/authentication) for the full setup.
</Note>

## Code examples

<CodeGroup>
  ```bash curl theme={null}
  curl "https://api.agntix.ai/v1/chat/chat/sessions?agentId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&state=OPEN&limit=20" \
    -H "x-api-key: pk_live_••••"
  ```

  ```javascript Node.js theme={null}
  const params = new URLSearchParams({
    agentId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    state: 'OPEN',
    page: '1',
    limit: '20',
  });

  const { data, pagination } = await fetch(
    `https://api.agntix.ai/v1/chat/chat/sessions?${params}`,
    { headers: { 'x-api-key': 'pk_live_••••' } },
  ).then(r => r.json());

  console.log(`${pagination.total} sessions found`);
  ```

  ```python Python theme={null}
  import httpx

  result = httpx.get(
      "https://api.agntix.ai/v1/chat/chat/sessions",
      headers={"x-api-key": "pk_live_••••"},
      params={
          "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "state": "OPEN",
          "page": 1,
          "limit": 20,
      },
  ).json()

  sessions = result["data"]
  print(f"{result['pagination']['total']} sessions found")
  ```
</CodeGroup>

## Sample response

```json theme={null}
{
  "data": [
    {
      "id": "ses_01j3m8xkqp8v2nw4f7g9hk0r",
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "platform": "SDK",
      "state": "OPEN",
      "metadata": { "userId": "usr_123" },
      "createdAt": "2026-04-29T09:00:00Z",
      "updatedAt": "2026-04-29T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
```


## OpenAPI

````yaml GET /v1/chat/chat/sessions
openapi: 3.0.3
info:
  title: Agntix API
  version: 1.0.0
  description: >-
    The Agntix API lets you build, deploy, and operate AI chat and voice agents.
    All requests are sent to `https://api.agntix.ai`. Authenticate with an API
    key (`x-api-key`) or a Clerk-issued JWT (`Authorization: Bearer <token>`).


    Base URL: `https://api.agntix.ai`
servers:
  - url: https://api.agntix.ai
    description: Production
security:
  - ApiKeyAuth: []
  - BearerAuth: []
tags:
  - name: Agents
    description: >-
      Create and manage AI agents — the core building block of Agntix. An agent
      encapsulates a system prompt, LLM, tools, knowledge store, and voice
      configuration.
  - name: Chat
    description: >-
      Open chat sessions with an agent and exchange messages. Supports streaming
      responses over SSE.
  - name: Voice
    description: >-
      List available voices and TTS/STT models, and create real-time voice
      sessions.
  - name: Tools
    description: >-
      Extend agent capabilities with API tools (webhook calls) or function tools
      (server-side logic).
  - name: Phone Numbers
    description: >-
      Provision and manage telephony numbers for inbound and outbound voice
      calls.
  - name: Models
    description: Browse available LLM, STT, and TTS models supported by Agntix.
  - name: Analytics
    description: Query call and agent-level performance metrics.
  - name: API Keys
    description: Create and manage organization-scoped API keys.
  - name: Contacts
    description: Manage customer contacts that can be linked to chat sessions.
  - name: Call Campaigns
    description: Launch and manage outbound call campaigns against a list of contacts.
  - name: Subscriptions
    description: View billing plans, usage quotas, and manage Stripe subscriptions.
paths:
  /v1/chat/chat/sessions:
    get:
      tags:
        - Chat
      summary: List sessions
      description: >-
        Returns a paginated list of chat sessions for your organization, ordered
        by most recent first.
      operationId: listSessions
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: agentId
          in: query
          description: Filter by agent.
          schema:
            type: string
            format: uuid
        - name: state
          in: query
          description: Filter by session state.
          schema:
            type: string
            enum:
              - OPEN
              - CLOSED
        - name: platform
          in: query
          description: Filter by originating platform.
          schema:
            type: string
            enum:
              - SDK
              - WEB
              - WHATSAPP
              - VOICE
      responses:
        '200':
          description: Paginated list of sessions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedSessions'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    PaginatedSessions:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/ChatSession'
        pagination:
          $ref: '#/components/schemas/Pagination'
    ChatSession:
      type: object
      properties:
        id:
          type: string
          example: ses_01j3m8xkqp8v2nw4f7g9hk0r
        agentId:
          type: string
          format: uuid
        platform:
          type: string
          example: SDK
        state:
          type: string
          enum:
            - OPEN
            - CLOSED
          example: OPEN
        metadata:
          type: object
          additionalProperties: true
        orgId:
          type: string
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    Pagination:
      type: object
      properties:
        page:
          type: integer
          example: 1
        limit:
          type: integer
          example: 20
        total:
          type: integer
          example: 47
        totalPages:
          type: integer
          example: 3
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: NOT_FOUND
            message:
              type: string
              example: Resource not found.
            status:
              type: integer
              example: 404
        meta:
          type: object
          properties:
            requestId:
              type: string
            timestamp:
              type: string
              format: date-time
  responses:
    Unauthorized:
      description: Missing or invalid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: UNAUTHORIZED
              message: Authentication required.
              status: 401
            meta:
              requestId: req_01j3m...
              timestamp: '2026-04-29T10:00:00Z'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Organization API key. Obtain from the
        [dashboard](https://app.agntix.ai/settings/api-keys). Format:
        `pk_live_…`
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Clerk-issued JWT. Use `Authorization: Bearer <token>`.'

````