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

# List Chats

> Returns a paginated list of chats with optional filters. Org-level API keys return all chats; user-level keys return only chats accessible to the user.



## OpenAPI

````yaml get /chats
openapi: 3.0.1
info:
  title: Attention Service V2
  description: Attention Service API V2
  termsOfService: https://www.attention.com/terms-of-use
  contact:
    name: Attention Team
    url: https://docs.attention.com/welcome
    email: support@attention.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 1.8.0
servers:
  - url: https://api.attention.tech/v2
security:
  - APIKeyHeader: []
paths:
  /chats:
    get:
      tags:
        - Chat
      summary: List Chats
      description: >-
        Returns a paginated list of chats with optional filters. Org-level API
        keys return all chats; user-level keys return only chats accessible to
        the user.
      operationId: listChats
      parameters:
        - name: filter[external_id]
          in: query
          description: Filter by external ID (exact match)
          schema:
            type: string
        - name: filter[type]
          in: query
          description: Filter by chat type (chat or email)
          schema:
            type: string
            enum:
              - chat
              - email
        - name: filter[title]
          in: query
          description: Filter by title (case-insensitive partial match)
          schema:
            type: string
        - name: filter[participant_name]
          in: query
          description: Filter by participant name (case-insensitive partial match)
          schema:
            type: string
        - name: filter[scorecard_id]
          in: query
          description: >-
            Filter by scorecard UUID(s) — returns chats evaluated with any of
            the given scorecards
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter[user_id]
          in: query
          description: Filter by user UUID(s)
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: filter[team_id]
          in: query
          description: Filter by team UUID(s)
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
        - name: from_date_time
          in: query
          description: Start of date range filter (ISO 8601 format)
          schema:
            type: string
            format: date-time
        - name: to_date_time
          in: query
          description: End of date range filter (ISO 8601 format)
          schema:
            type: string
            format: date-time
        - name: exclude_transcript
          in: query
          description: If true, omit transcript data from response to reduce payload size
          schema:
            type: boolean
            default: false
        - name: page
          in: query
          description: Page number for pagination (starts from 1)
          schema:
            minimum: 1
            type: integer
            default: 1
        - name: size
          in: query
          description: Number of items per page (min 1, max 50)
          schema:
            maximum: 50
            minimum: 1
            type: integer
            default: 10
      responses:
        '200':
          description: Chats successfully returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListChatsResponse'
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/ListChatsResponse'
        '401':
          description: Valid API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Unexpected error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListChatsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Chat'
        meta:
          $ref: '#/components/schemas/Meta'
      example:
        data:
          - id: chat-uuid-123
            externalId: slack-channel-xyz
            applicationName: slack
            title: Sales Q1 Planning
            type: chat
            userId: user-uuid-456
            teamId: team-uuid-789
            dateStart: '2024-03-18T09:00:00Z'
            createdAt: '2024-03-18T09:00:00Z'
            participants: []
            transcript: []
        meta:
          totalRecords: 1
    Error:
      type: object
      properties:
        id:
          type: string
          description: A unique identifier for the error.
        status:
          type: string
          description: >-
            The HTTP status code applicable to this problem, expressed as a
            string value.
        code:
          type: string
          description: An application-specific error code, expressed as a string value.
        title:
          type: string
          description: A short, human-readable summary of the problem.
        detail:
          type: string
          description: >-
            A human-readable explanation specific to this occurrence of the
            problem.
        source:
          type: object
          properties:
            pointer:
              type: string
            parameter:
              type: string
        meta:
          type: object
          properties: {}
      example:
        id: not_found_error
        status: '404'
        code: '404'
        title: Not Found Error
        detail: The requested resource was not found
        source:
          pointer: /data/attributes/id
    Chat:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the chat
        externalId:
          type: string
          description: External identifier from the source system
        applicationName:
          type: string
          description: Name of the application that created the chat
        title:
          type: string
          description: Title of the chat
        type:
          type: string
          description: Type of chat (chat or email)
          enum:
            - chat
            - email
        userId:
          type: string
          description: UUID of the user who owns the chat
        teamId:
          type: string
          description: UUID of the team the chat belongs to
        participants:
          type: array
          description: List of chat participants
          items:
            $ref: '#/components/schemas/ChatParticipant'
        transcript:
          type: array
          description: Chat transcript entries (omitted when exclude_transcript=true)
          items:
            $ref: '#/components/schemas/ChatTranscriptItem'
        dateStart:
          type: string
          description: When the chat started
          format: date-time
        createdAt:
          type: string
          description: When the chat record was created
          format: date-time
      example:
        id: chat-uuid-123
        externalId: slack-channel-xyz
        applicationName: slack
        title: Sales Q1 Planning
        type: chat
        userId: user-uuid-456
        teamId: team-uuid-789
        dateStart: '2024-03-18T09:00:00Z'
        createdAt: '2024-03-18T09:00:00Z'
        participants:
          - externalId: slack-user-1
            name: Jane Smith
            email: jane@example.com
            participantType: user
            userUuid: user-uuid-456
        transcript:
          - author: Jane Smith
            authorEmail: jane@example.com
            sentence: Let's discuss our targets.
            datetime: '2024-03-18T09:05:00Z'
    Meta:
      type: object
      properties:
        pageCount:
          type: integer
        totalRecords:
          type: integer
        pageNumber:
          type: integer
        pageSize:
          type: integer
      example:
        pageCount: 5
        totalRecords: 100
        pageNumber: 1
        pageSize: 20
    ChatParticipant:
      type: object
      properties:
        externalId:
          type: string
          description: External identifier of the participant
        name:
          type: string
          description: Display name of the participant
        email:
          type: string
          description: Email address of the participant
        participantType:
          type: string
          description: Type of participant
          enum:
            - prospect
            - user
            - bot
        userUuid:
          type: string
          description: UUID of the associated user (if applicable)
      example:
        externalId: slack-user-123
        name: Jane Smith
        email: jane@example.com
        participantType: user
        userUuid: user-uuid-456
    ChatTranscriptItem:
      type: object
      properties:
        sentence:
          type: string
          description: The text content of the transcript entry
        author:
          type: string
          description: Name of the author
        authorEmail:
          type: string
          description: Email address of the author
        datetime:
          type: string
          description: Timestamp of the transcript entry
          format: date-time
      example:
        author: Jane Smith
        authorEmail: jane@example.com
        sentence: Let's discuss the Q1 targets.
        datetime: '2024-03-18T09:05:00Z'
  securitySchemes:
    APIKeyHeader:
      type: apiKey
      name: Authorization
      in: header

````