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

# List chats

> Page through your workspace's text conversations, newest first.

<Note>
  **Cursor pagination.** Pass the response's `next_cursor` back as `?cursor=` for the next page;
  `has_more` is `false` on the last page. Cursors are opaque - don't parse them.
</Note>

<Tip>
  `transcript` is `null` in list items unless you pass `include=transcript`.
</Tip>

<Note>
  Use `?origin=widget` to see only real end-user conversations from your embedded widget, excluding
  chat tests run from the Vocily dashboard.
</Note>


## OpenAPI

````yaml developers/openapi.json GET /v1/chats
openapi: 3.1.0
info:
  title: Vocily API
  description: >-
    Public REST API for Vocily. Build and configure an agent, publish a version
    and put it live, place outbound calls, and read back calls, chats and what
    the agent remembered. Authenticate with a workspace API key as a Bearer
    token.


    Some things stay in the dashboard, by design: creating an API key, buying or
    connecting a phone number, setting an agent's webhook URL, connecting
    WhatsApp and its templates, building HTTP tools, and running batch
    campaigns.
  version: v1
servers:
  - url: https://api.vocily.ai
    description: Production
security: []
paths:
  /v1/chats:
    get:
      tags:
        - chats
      summary: List Chats
      description: >-
        List this workspace's text conversations, newest first,
        cursor-paginated.


        Same paging contract as `GET /v1/calls`, so one loop reads both.
        `transcript` is omitted unless you ask for it with `?include=transcript`
        — it is large, and get-by-id always includes it.
      operationId: list_chats_v1_chats_get
      parameters:
        - name: agent_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by agent id
            title: Agent Id
          description: Filter by agent id
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter by status
            title: Status
          description: Filter by status
        - name: origin
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Filter by who started it — comma-list of: widget | dashboard. Use
              it to exclude your own dashboard chat tests, e.g.
              `?origin=widget`. Rows with an unknown origin are excluded when
              this is set.
            title: Origin
          description: >-
            Filter by who started it — comma-list of: widget | dashboard. Use it
            to exclude your own dashboard chat tests, e.g. `?origin=widget`.
            Rows with an unknown origin are excluded when this is set.
        - name: date_from
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: started_at >= this datetime
            title: Date From
          description: started_at >= this datetime
        - name: date_to
          in: query
          required: false
          schema:
            anyOf:
              - type: string
                format: date-time
              - type: 'null'
            description: started_at <= this datetime
            title: Date To
          description: started_at <= this datetime
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Opaque cursor from a previous response's `next_cursor`
            title: Cursor
          description: Opaque cursor from a previous response's `next_cursor`
        - name: include
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: 'Comma-list of heavy fields to include. Currently: `transcript`'
            title: Include
          description: 'Comma-list of heavy fields to include. Currently: `transcript`'
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 100
            minimum: 1
            default: 20
            title: Limit
          description: Maximum records to return in one page.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicChatList'
              example:
                data:
                  - id: 00000015-0000-4000-8000-000000000015
                    agent_id: 00000002-0000-4000-8000-000000000002
                    agent_name: zdfbdhjfbdkfbdkjfbkdjfb
                    agent_version: 7
                    status: completed
                    origin: dashboard
                    turn_count: 2
                    created_at: '2026-09-14T13:29:19.058795Z'
                    ended_at: '2026-09-14T13:29:33.914425Z'
                    metadata: null
                    variables: null
                    cost:
                      currency: USD
                      total: 0.002
                      rate_per_reply: 0.001
                    custom_analysis:
                      Default Analysis:
                        Outcome: >-
                          Awaiting clarification on property type (house or
                          flat) and further needs; no resolution yet
                        Language: Hindi/Hinglish
                        Call Summary: >-
                          The caller shared a phone number and the agent asked
                          for whether they are looking for a house or a flat,
                          engaging in initial needs gathering. The call is in
                          early questioning; no property details or decisions
                          were made yet.
                        User Sentiment: neutral
                    transcript: null
                    dashboard_url: >-
                      https://app.vocily.ai/calls?execution_id=00000015-0000-4000-8000-000000000015
                  - id: 00000016-0000-4000-8000-000000000016
                    agent_id: 00000002-0000-4000-8000-000000000002
                    agent_name: zdfbdhjfbdkfbdkjfbkdjfb
                    agent_version: 7
                    status: completed
                    origin: dashboard
                    turn_count: 2
                    created_at: '2026-09-14T13:28:57.514415Z'
                    ended_at: '2026-09-14T13:29:07.043869Z'
                    metadata: null
                    variables: null
                    cost:
                      currency: USD
                      total: 0.002
                      rate_per_reply: 0.001
                    custom_analysis: null
                    transcript: null
                    dashboard_url: >-
                      https://app.vocily.ai/calls?execution_id=00000016-0000-4000-8000-000000000016
                has_more: true
                next_cursor: >-
                  eyJzIjoiMjAyNi0wOS0xNFQxMzoyODo1Ny41MTQ0MTUrMDA6MDAiLCJpIjoiYTA4ODgwYzktOTJhNC00MDA1LWI4OWMtZTcyYWYxOWQ5MTNhIn0
        '400':
          description: The pagination cursor is invalid or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                detail:
                  code: invalid_cursor
                  message: The pagination cursor is invalid or expired.
                code: BAD_REQUEST
        '401':
          description: Missing or invalid API key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                detail: Invalid API key
                code: UNAUTHORIZED
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          description: Rate limit exceeded — honor `Retry-After`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                code: rate_limited
      security:
        - bearerAuth: []
components:
  schemas:
    PublicChatList:
      properties:
        data:
          items:
            $ref: '#/components/schemas/PublicChatRead'
          type: array
          title: Data
          description: The page of chats.
        has_more:
          type: boolean
          title: Has More
          description: Whether another page exists.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: Pass as `cursor` to fetch the next page. `null` on the last page.
      type: object
      required:
        - data
        - has_more
        - next_cursor
      title: PublicChatList
      description: >-
        Envelope for `GET /v1/chats`. Same cursor contract as `GET /v1/calls`,
        so one paging loop reads both.
    ApiError:
      type: object
      description: >-
        Error envelope. `code` is derived from the HTTP status, so branch on it
        for the CLASS of failure; the specific reason is `detail.code`. Every
        public refusal carries both.
      properties:
        detail:
          type: object
          description: >-
            The reason. `code` is the domain reason (e.g. `call_not_found`) and
            `message` is a sentence safe to log. On a `422` it also carries
            `errors[]`, one entry per rejected field — see
            `HTTPValidationError`.
          properties:
            code:
              type: string
              example: call_not_found
            message:
              type: string
              example: Call not found
          required:
            - code
            - message
        code:
          type: string
          description: Derived from the HTTP status, not the domain reason.
          example: NOT_FOUND
    HTTPValidationError:
      type: object
      title: HTTPValidationError
      description: >-
        A request the API could not read: a field of the wrong type, out of
        range, missing, or one we do not accept. Same envelope as every other
        error.
      properties:
        detail:
          type: object
          description: >-
            What was wrong, as `code`, a one-line `message`, and every offending
            field in `errors`.
          required:
            - code
            - message
            - errors
          properties:
            code:
              type: string
              enum:
                - validation_error
            message:
              type: string
              description: >-
                The first problem in one line, with a count of the rest — e.g.
                `model.temperature: Input should be less than or equal to 2 (and
                1 more)`.
            errors:
              type: array
              items:
                $ref: '#/components/schemas/ValidationError'
              description: >-
                One entry per offending field. **Every problem is reported at
                once**, not just the first, so a malformed body needs one round
                trip to fix rather than one per field.
        code:
          type: string
          enum:
            - VALIDATION_ERROR
          description: Derived from the HTTP status, as on every error.
    PublicChatRead:
      properties:
        id:
          type: string
          title: Id
          description: The chat's id.
        agent_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Id
          description: Which agent handled it.
        agent_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Agent Name
          description: >-
            The agent's name as it was at the time — snapshotted, so a later
            rename does not rewrite history.
        agent_version:
          anyOf:
            - type: integer
            - type: 'null'
          title: Agent Version
          description: Which version of the agent answered.
        status:
          type: string
          title: Status
          description: >-
            Where the chat got to — `started`, `in_progress`, or `completed`. A
            chat has no failure state: it cannot ring, be declined or reach
            voicemail. `completed` means **no longer active**, which includes a
            visitor simply closing the tab.
        origin:
          anyOf:
            - type: string
            - type: 'null'
          title: Origin
          description: >-
            `widget` for a real end user on your site, `dashboard` for our own
            chat test button. `null` means unknown on older rows.
        turn_count:
          type: integer
          title: Turn Count
          description: >-
            Assistant replies in the session. **This is the billing unit for
            text** — voice bills on `duration_seconds`, which is always `null`
            here — so it is published rather than left for you to count out of
            the transcript and get a different answer than the invoice.
        created_at:
          type: string
          format: date-time
          title: Created At
          description: When the chat started (UTC, ISO 8601).
        ended_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Ended At
          description: When it ended. `null` while still open.
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Your own passthrough, unchanged.
        variables:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Variables
          description: The chat's own variables. Only your `custom` bag.
        cost:
          anyOf:
            - $ref: '#/components/schemas/PublicChatCost'
            - type: 'null'
          description: What the chat cost. Priced per assistant reply, not per minute.
        custom_analysis:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Analysis
          description: Everything your analysis groups extracted, keyed by group then item.
        transcript:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Transcript
          description: >-
            The conversation. Omitted (`null`) on the LIST unless you pass
            `?include=transcript`.
        dashboard_url:
          type: string
          title: Dashboard Url
          description: Deep link to this chat in the Vocily dashboard.
      type: object
      required:
        - id
        - agent_id
        - agent_name
        - agent_version
        - status
        - origin
        - turn_count
        - created_at
        - ended_at
        - metadata
        - variables
        - cost
        - custom_analysis
        - transcript
        - dashboard_url
      title: PublicChatRead
      description: >-
        One text conversation — a widget chat or a WhatsApp thread.


        Separate from a call because a chat has no numbers, no duration, no
        recording and no transfer, and is priced per assistant reply rather than
        per minute.


        Read-only. A chat begins when someone opens your widget or messages your
        WhatsApp number, so there is no endpoint that starts one.
    ValidationError:
      type: object
      title: ValidationError
      required:
        - field
        - message
        - type
      properties:
        field:
          type: string
          description: >-
            The offending field as a path from the root of your request —
            `voice.speed`, `variables[0].key`, or `query.limit` for a query
            parameter. **This is the field to read.**
        message:
          type: string
          description: What is wrong with it, in plain language.
        type:
          type: string
          description: >-
            A stable machine code for the kind of failure, e.g.
            `extra_forbidden` for a field we do not accept, `missing` for a
            required one, or `less_than_equal` for a number out of range. Switch
            on this rather than on `message`, which may be reworded.
    PublicChatCost:
      properties:
        currency:
          type: string
          title: Currency
          description: ISO currency code.
          default: USD
        total:
          type: number
          title: Total
          description: What the chat cost, in `currency`. Dollars.
        rate_per_reply:
          anyOf:
            - type: number
            - type: 'null'
          title: Rate Per Reply
          description: >-
            The per-reply rate it was billed at, in dollars per assistant reply
            at the time of the chat. Text is priced per reply, not per minute.
      type: object
      required:
        - total
      title: PublicChatCost
      description: >-
        What a chat cost. Priced per assistant REPLY, which is why this carries
        no `rate_per_min` — that is the voice unit and would be wrong here.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Your API key as a Bearer token, e.g. `Authorization: Bearer vk_…`.'

````