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

# List archives

> Returns a list of the chats an agent has access to. Together with a chat, the events of one thread from this chat are returned.

The list classification is based on threads — 1 chat per 1 thread. The same chat object may appear on the list several times, but each time with a different thread. The returned chat is a complete object, not only a chat summary.

**Required scopes:** <Tooltip tip="To find threads from all groups.">`chats--all:ro`</Tooltip> or <Tooltip tip="To find threads from groups that the requester (related to the token) is a member of.">`chats--access:ro`</Tooltip>


## OpenAPI

````yaml /api/agent-chat/v3.5/openapi.json post /action/list_archives
openapi: 3.0.0
info:
  title: Agent Chat API
  description: >-
    The Agent Chat API allows you to manage chats, threads, events, and agent
    state.
  version: '3.5'
servers:
  - url: https://api.livechatinc.com/v3.5/agent
    description: Production server
security: []
paths:
  /action/list_archives:
    post:
      tags:
        - Chats
      summary: List archives
      description: >-
        Returns a list of the chats an agent has access to. Together with a
        chat, the events of one thread from this chat are returned.


        The list classification is based on threads — 1 chat per 1 thread. The
        same chat object may appear on the list several times, but each time
        with a different thread. The returned chat is a complete object, not
        only a chat summary.
      operationId: list-archives
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListArchivesRequest'
            example:
              filters:
                event_types:
                  values:
                    - message
                    - filled_form
      responses:
        '200':
          description: Archived chats.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListArchivesResponse'
              example:
                chats:
                  - id: PJ0MRSHTDG
                    users:
                      - id: smith@example.com
                        name: Agent Smith
                        email: smith@example.com
                        type: agent
                        present: true
                        avatar: https://cdn.livechat-files.com/api/file/avatar.png
                        visibility: all
                    thread:
                      id: K600PKZON8
                      active: false
                      user_ids:
                        - smith@example.com
                      events:
                        - id: QBT14H0Y3Y_1
                          created_at: '2026-06-28T11:45:32.269000Z'
                          visibility: all
                          type: message
                          properties:
                            0805e283233042b37f460ed8fbf22160:
                              event_property: property_value
                          text: Hello there
                          author_id: smith@example.com
                      properties:
                        0805e283233042b37f460ed8fbf22160:
                          thread_property: property_value
                      access:
                        group_ids:
                          - 0
                      created_at: '2026-06-28T11:44:58.829000Z'
                      previous_thread_id: K600PKZOM8
                      next_thread_id: K600PKZOO8
                      previous_accessible_thread_id: K600PKZOM8
                      next_accessible_thread_id: K600PKZOO8
                    properties:
                      0805e283233042b37f460ed8fbf22160:
                        chat_property: property_value
                    access:
                      group_ids:
                        - 0
                    is_followed: false
                found_chats: 42
                next_page_id: MTUxNzM5ODEzMTQ5Ng==
                previous_page_id: MTUxNzM5ODEzMTQ5Ng==
      security:
        - PersonalAccessToken: []
        - OAuth2BearerToken:
            - chats--all:ro
components:
  schemas:
    ListArchivesRequest:
      type: object
      properties:
        filters:
          type: object
          description: Archive filters.
          properties:
            query:
              type: string
              description: Full-text search query.
            from:
              type: string
              description: >-
                Start date in RFC3339 format:
                `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.
            to:
              type: string
              description: 'End date in RFC3339 format: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.'
            chat_ids:
              type: array
              items:
                type: string
              maxItems: 1000
              description: Array of chat IDs.
            thread_ids:
              type: array
              items:
                type: string
              maxItems: 20
              description: >-
                Array of thread IDs. Cannot be used with other filters or
                pagination.
            group_ids:
              type: array
              items:
                type: integer
              maxItems: 200
              description: Array of group IDs.
            properties:
              type: object
              description: >-
                Property filters. Use the format
                `filters.properties.<namespace>.<name>.<properties_filter_type>`.


                `<properties_filter_type>` can be one of:


                - `exists` (`bool`).

                - `values` (`type[]`) — an array with a specific type for the
                property: `string`, `int`, or `bool`.

                - `exclude_values` (`type[]`) — an array with a specific type
                for the property: `string`, `int`, or `bool`.


                Only one value is allowed per property.
              additionalProperties: true
            agents:
              type: object
              description: >-
                Agent filters. If `exists` is `false`: returns unassigned chats.
                If `true`: returns assigned ones.


                Use the format `filters.agents.<agents_filter_type>`.


                `<agents_filter_type>` can be one of:


                - `exists` (`bool`).

                - `values` (`string[]`) — an array of values to match.

                - `exclude_values` (`string[]`) — an array of values to exclude.

                - `require_every_value` (`bool`) — if `true`, returns only chats
                that have all elements passed in `values` or `exclude_values`.


                Only one of `exists`, `values`, or `exclude_values` can be
                passed at a time.
              additionalProperties: true
            tags:
              type: object
              description: >-
                Tag filters.


                Use the format `filters.tags.<tags_filter_type>`.


                `<tags_filter_type>` can be one of:


                - `exists` (`bool`).

                - `values` (`string[]`) — an array of values to match.

                - `exclude_values` (`string[]`) — an array of values to exclude.

                - `require_every_value` (`bool`) — if `true`, returns only chats
                that have all elements passed in `values` or `exclude_values`.


                Only one of `exists`, `values`, or `exclude_values` can be
                passed at a time.
              additionalProperties: true
            sales:
              type: object
              description: >-
                Sales filters.


                Use the format `filters.sales.<sales_filter_type>`.


                `<sales_filter_type>` can be one of:


                - `exists` (`bool`).

                - `values` (`string[]`) — an array of values to match.

                - `exclude_values` (`string[]`) — an array of values to exclude.

                - `require_every_value` (`bool`) — if `true`, returns only chats
                that have all elements passed in `values` or `exclude_values`.


                Only one of `exists`, `values`, or `exclude_values` can be
                passed at a time.
              additionalProperties: true
            goals:
              type: object
              description: >-
                Goals filters.


                Use the format `filters.goals.<goals_filter_type>`.


                `<goals_filter_type>` can be one of:


                - `exists` (`bool`).

                - `values` (`string[]`) — an array of values to match.

                - `exclude_values` (`string[]`) — an array of values to exclude.

                - `require_every_value` (`bool`) — if `true`, returns only chats
                that have all elements passed in `values` or `exclude_values`.


                Only one of `exists`, `values`, or `exclude_values` can be
                passed at a time.
              additionalProperties: true
            forms:
              type: array
              description: >-
                Form filters. Each item in the array can include the following
                fields:


                - `from` (`string`) — start date in RFC3339 format with
                microseconds: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.

                - `to` (`string`) — end date in RFC3339 format with
                microseconds: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.

                - `exists` (`bool`) — if `true`, returns only surveys with a
                `survey_id`.

                - `type` (`string`) — allowed values: `pre_chat`, `post_chat`.

                - `values` (`string[]`) — an array of `answer_id` values.

                - `exclude_values` (`string[]`) — an array of `answer_id` values
                to exclude.

                - `groups.values` (`int[]`) — an array of group IDs.

                - `groups.exclude_values` (`int[]`) — an array of group IDs to
                exclude.
              items:
                type: object
                additionalProperties: true
            event_types:
              type: object
              description: >-
                Event type filters. Use the format
                `filters.event_types.<event_type_filter_type>`.


                `<event_type_filter_type>` can be one of:


                - `values` (`string[]`) — an array of event types; duplicates
                are ignored.

                - `exclude_values` (`string[]`) — an array of event types to
                exclude; duplicates are ignored.

                - `require_every_value` (`bool`) — if `true`, returns only chats
                that have all elements passed in `values` or `exclude_values`.


                Only one of `values` or `exclude_values` can be passed at a
                time.
              additionalProperties: true
            greetings:
              type: object
              description: >-
                Greeting filters. Use the format
                `filters.greetings.<greetings_filter_type>`.


                `<greetings_filter_type>` can be one of:


                - `from` (`string`) — start date in RFC3339 format with
                microseconds: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.

                - `to` (`string`) — end date in RFC3339 format with
                microseconds: `YYYY-MM-DDTHH:MM:SS.ssssss+HH:MM`.

                - `exists` (`bool`).

                - `values` (`int[]`) — an array of greeting IDs.

                - `exclude_values` (`int[]`) — an array of greeting IDs to
                exclude.

                - `groups.values` (`int[]`) — an array of group IDs.

                - `groups.exclude_values` (`int[]`) — an array of group IDs to
                exclude.
              additionalProperties: true
            agent_response:
              type: object
              description: >-
                Agent response filters. Use the format
                `filters.agent_response.<agent_response_filter_type>`.


                `<agent_response_filter_type>` can be one of:


                - `exists` (`bool`).

                - `first` (`bool`) — modifier that makes the other
                `agent_response` filters operate only on agents' first response.

                - `agents.values` (`string[]`) — an array of agent IDs.

                - `agents.exclude_values` (`string[]`) — an array of agent IDs
                to exclude.

                - `groups.values` (`int[]`) — an array of group IDs.

                - `groups.exclude_values` (`int[]`) — an array of group IDs to
                exclude.
              additionalProperties: true
            agent_types:
              type: object
              description: >-
                Agent type filters. Use the format
                `filters.agent_types.<agent_type_filter_type>`.


                `<agent_type_filter_type>` can be one of:


                - `all_values` (`string[]`) — an array of agent type values.

                - `any_values` (`string[]`) — an array of agent type values.

                - `exclude_values` (`string[]`) — an array of agent type values.


                Allowed agent type values: `human`, `chatbot`, `ai_agent`. Each
                value can be used only once across all arrays.


                You can provide more than one filter type at a time, for example
                `all_values` and `exclude_values`.
              additionalProperties: true
            customer_countries:
              type: object
              description: >-
                Customer country filters. Supports country codes in `ISO 3166-1
                Alpha-2` format.
              additionalProperties: true
            customer_id:
              type: string
              description: Customer ID to filter by.
            customer_email:
              type: string
              description: Customer email to filter by.
        highlights:
          type: object
          description: Highlight configuration for search query matches.
          properties:
            pre_tag:
              type: string
              default: <em>
              description: Opening HTML tag for highlighted matches.
            post_tag:
              type: string
              default: </em>
              description: Closing HTML tag for highlighted matches.
        sort_order:
          type: string
          enum:
            - asc
            - desc
          default: desc
          description: '`asc` for oldest chats first, `desc` for newest chats first.'
        limit:
          type: integer
          default: 10
          minimum: 1
          maximum: 100
          description: Maximum number of records per page.
        page_id:
          type: string
          description: Pagination token.
    ListArchivesResponse:
      type: object
      properties:
        chats:
          type: array
          items:
            $ref: '#/components/schemas/Chat'
          description: Array of [chat objects](/api/agent-chat/v3.5/data-structures#chats).
        found_chats:
          type: integer
          description: Total number of found chats.
        next_page_id:
          type: string
          description: Pagination token for the next page.
        previous_page_id:
          type: string
          description: Pagination token for the previous page.
    Chat:
      type: object
      description: >-
        Full chat object. For full field details, see the [Agent Chat API data
        structures reference](/api/agent-chat/v3.5/data-structures).
      properties:
        id:
          type: string
          description: Chat ID.
        users:
          type: array
          items:
            $ref: '#/components/schemas/User'
          description: Chat users.
        thread:
          $ref: '#/components/schemas/Thread'
        properties:
          $ref: '#/components/schemas/Properties'
        access:
          $ref: '#/components/schemas/Access'
        is_followed:
          type: boolean
          description: Whether the requester follows the chat.
    User:
      type: object
      description: >-
        User object (agent or customer). For full field details, see the [Agent
        Chat API data structures
        reference](/api/agent-chat/v3.5/data-structures).
      properties:
        id:
          type: string
          description: User ID.
        type:
          type: string
          enum:
            - agent
            - customer
          description: User type.
        name:
          type: string
          description: User's display name.
        email:
          type: string
          description: User's email address (agents only).
        present:
          type: boolean
          description: Whether the user is currently present in the chat.
    Thread:
      type: object
      description: >-
        Thread object. For full field details, see the [Agent Chat API data
        structures reference](/api/agent-chat/v3.5/data-structures).
      properties:
        id:
          type: string
          description: Thread ID.
        chat_id:
          type: string
          description: Chat ID.
        active:
          type: boolean
          description: Whether the thread is active.
        user_ids:
          type: array
          items:
            type: string
          description: IDs of users present in the thread.
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: Thread events.
        properties:
          $ref: '#/components/schemas/Properties'
        access:
          $ref: '#/components/schemas/Access'
        created_at:
          type: string
          format: date-time
          description: Thread creation timestamp (RFC3339 with microseconds).
        previous_thread_id:
          type: string
          description: ID of the previous thread in the chat (if exists).
        next_thread_id:
          type: string
          description: ID of the next thread in the chat (if exists).
    Properties:
      type: object
      description: Custom properties organized by namespace, then property name.
      additionalProperties:
        type: object
        additionalProperties: true
    Access:
      type: object
      description: >-
        [Access object](/api/agent-chat/v3.5/data-structures#access) defining
        which groups can access the chat or thread.
      properties:
        group_ids:
          type: array
          items:
            type: integer
          description: Array of group IDs with access. `0` means all groups.
    Event:
      type: object
      description: >-
        Event object. Event types include `message`, `file`, `form`,
        `filled_form`, `rich_message`, `custom`, `system_message`, and `system`.
        For full field details per type, see the [Agent Chat API data structures
        reference](/api/agent-chat/v3.5/data-structures).
      properties:
        id:
          type: string
          description: Event ID.
        type:
          type: string
          description: Event type.
        created_at:
          type: string
          format: date-time
          description: Event creation timestamp (RFC3339 with microseconds).
        author_id:
          type: string
          description: ID of the event author.
        visibility:
          type: string
          enum:
            - all
            - agents
          description: Event visibility.
        properties:
          $ref: '#/components/schemas/Properties'
  securitySchemes:
    PersonalAccessToken:
      description: >-
        Use your `account ID` as the username and your personal access token
        (PAT) as the password, or pass a Base64-encoded value directly in the
        Authorization header. For more information, see the <a
        href="/authentication/personal-access-tokens">personal access tokens
        guide</a>.
      type: http
      scheme: basic
    OAuth2BearerToken:
      description: >-
        This API uses OAuth2 with the implicit grant flow. <a
        href="/authentication/oauth-authorization#implicit-grant">Learn about
        the implicit grant flow.</a>
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.livechat.com
          scopes:
            chats--all:ro: Read all chats
            chats--all:rw: Read and write all chats
            chats--access:ro: Read chats from groups the agent is a member of
            chats--access:rw: Read and write chats from groups the agent is a member of
        authorizationCode:
          authorizationUrl: https://accounts.livechat.com
          tokenUrl: https://accounts.livechat.com/token
          scopes:
            chats--all:ro: Read all chats
            chats--all:rw: Read and write all chats
            chats--access:ro: Read chats from groups the agent is a member of
            chats--access:rw: Read and write chats from groups the agent is a member of

````