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

# Conversations History API

> Access complete conversation history with filtering and pagination

This API endpoint provides access to the complete history of business message conversations with advanced filtering and
pagination capabilities. It's designed for administrative dashboards, reporting, and analytics purposes.

## API Endpoint

```
GET /api/business_messages/all-threads-history
```

<Warning>
  **Authentication:** Requires staff-level permissions
</Warning>

**Content-Type:** `application/json`
**Response Format:** JSON with pagination

## Overview

The conversations history API allows administrators to:

* Retrieve paginated conversation threads
* Filter conversations by multiple criteria
* Access detailed thread information including user data, evaluations, and metadata
* Export and analyze conversation patterns

## Request Parameters

All parameters are optional and can be combined for advanced filtering:

### Date Filtering

| Parameter    | Type   | Description                                                |
| ------------ | ------ | ---------------------------------------------------------- |
| `start_date` | string | Filter conversations created after this date (ISO format)  |
| `end_date`   | string | Filter conversations created before this date (ISO format) |

### User Filtering

| Parameter        | Type   | Description                      |
| ---------------- | ------ | -------------------------------- |
| `email`          | string | Filter by user email address     |
| `user_type`      | string | Filter by user permission type   |
| `reviewer_email` | string | Filter by reviewer email address |

### Conversation Content

| Parameter    | Type   | Description                                  |
| ------------ | ------ | -------------------------------------------- |
| `agent_name` | string | Filter by AI agent name used in conversation |
| `tag`        | string | Filter by conversation tag                   |
| `evaluation` | string | Filter by thread evaluation status           |

### Conversation Status

| Parameter        | Type    | Description                                             |
| ---------------- | ------- | ------------------------------------------------------- |
| `support_asked`  | boolean | Filter conversations where human support was requested  |
| `need_review`    | boolean | Filter conversations that need manual review            |
| `ticket_created` | boolean | Filter conversations where a support ticket was created |

### Knowledge Base

| Parameter           | Type   | Description                          |
| ------------------- | ------ | ------------------------------------ |
| `knowledge_source`  | string | Filter by knowledge source used      |
| `knowledge_page_id` | string | Filter by specific knowledge page ID |

### Pagination

| Parameter | Type    | Description                             |
| --------- | ------- | --------------------------------------- |
| `page`    | integer | Page number for pagination (default: 1) |

### Message Data

| Parameter          | Type    | Description                                                      |
| ------------------ | ------- | ---------------------------------------------------------------- |
| `include_messages` | boolean | Include full message details within each thread (default: false) |

**Note:** Each page contains 50 conversations. Use the `count` field in the response to calculate total pages.

## Response Format

The API returns a paginated response with the following structure:

```json theme={null}
{
  "count": 1250,
  "items": [
    {
      "id": "thread-uuid",
      "title": "Conversation title",
      "last_message_date": "2024-12-06T14:30:00Z",
      "creation_date": "2024-12-06T14:25:00Z",
      "evaluation": "good",
      "llm_judge_evaluated": true,
      "llm_judge_need_review": false,
      "llm_judge_improvement": "No improvements needed",
      "user": {
        "id": "user-uuid",
        "email": "user@example.com",
        "first_name": "John",
        "last_name": "Doe"
      },
      "reviewer": {
        "id": "reviewer-uuid",
        "email": "admin@example.com",
        "first_name": "Admin",
        "last_name": "User"
      },
      "agent_names": [
        "Customer Support AI",
        "Technical AI"
      ],
      "messages_count": 8,
      "ask_to_talk_to_human": false,
      "user_type": "premium",
      "tags": [
        {
          "id": "tag-uuid",
          "name": "billing"
        }
      ],
      "ticket_created": false
    }
  ]
}
```

### Response Fields

#### Thread Information

* `id`: Unique thread identifier
* `title`: Conversation title/subject
* `last_message_date`: Timestamp of the last message
* `creation_date`: Thread creation timestamp
* `messages_count`: Total number of messages in the thread

#### Evaluation & Quality

* `evaluation`: Manual evaluation status (good, bad, neutral, etc.)
* `llm_judge_evaluated`: Whether AI judge has evaluated the conversation
* `llm_judge_need_review`: Whether AI judge flagged for manual review
* `llm_judge_improvement`: AI judge improvement suggestions

#### User Information

* `user`: Complete user object with id, email, first\_name, last\_name
* `reviewer`: Reviewer user object (if conversation was reviewed)
* `user_type`: User permission level/type

#### Conversation Context

* `agent_names`: Array of AI agent names that participated
* `ask_to_talk_to_human`: Whether user requested human support
* `tags`: Array of conversation tags
* `ticket_created`: Whether a support ticket was generated

#### Messages (when `include_messages=true`)

When the `include_messages` parameter is set to `true`, each thread will include a `messages` array:

```json theme={null}
{
  "messages": [
    {
      "id": "message-uuid",
      "content": "Hello, I need help with my account",
      "role": "user",
      "answer_text": null,
      "thread": {
        "id": "thread-uuid",
        "title": "Account Help"
      },
      "knowledge_sources": [],
      "isStaff": false,
      "languages": ["en"],
      "agent": {
        "id": "agent-uuid",
        "name": "Customer Support AI"
      }
    },
    {
      "id": "message-uuid-2",
      "content": "I'd be happy to help you with your account.",
      "role": "assistant",
      "answer_text": "I'd be happy to help you with your account.",
      "thread": {
        "id": "thread-uuid",
        "title": "Account Help"
      },
      "knowledge_sources": [
        {
          "id": "source-uuid",
          "position": 1
        }
      ],
      "isStaff": false,
      "languages": ["en"],
      "agent": {
        "id": "agent-uuid",
        "name": "Customer Support AI"
      }
    }
  ]
}
```

* `messages`: Array of all messages in chronological order
* Each message includes agent information, knowledge sources, and role details
* Messages are optimized with efficient database queries to prevent performance issues

## Usage Examples

### Basic Request

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history" \
     -H "x-api-key: YOUR_API_KEY"
```

### Filter by Date Range

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?start_date=2024-12-01T00:00:00Z&end_date=2024-12-07T23:59:59Z" \
     -H "x-api-key: YOUR_API_KEY"
```

### Filter by User and Agent

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?email=user@example.com&agent_name=Support%20AI" \
     -H "x-api-key: YOUR_API_KEY"
```

### Filter Conversations Needing Review

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?need_review=true&evaluation=bad" \
     -H "x-api-key: YOUR_API_KEY"
```

### Pagination Example

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?page=2" \
     -H "x-api-key: YOUR_API_KEY"
```

### Include Messages in Response

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?include_messages=true" \
     -H "x-api-key: YOUR_API_KEY"
```

### Combined Filtering with Messages

```bash theme={null}
curl -X GET "https://your_tenant.api.example.com/api/business_messages/all-threads-history?evaluation=bad&include_messages=true&page=1" \
     -H "x-api-key: YOUR_API_KEY"
```

## Error Responses

### 403 Forbidden

```json theme={null}
{
  "error": "Staff permissions required"
}
```

### 400 Bad Request

```json theme={null}
{
  "error": "Invalid date format"
}
```

## Performance Considerations

* **Pagination**: Always use pagination for large datasets. Each page is limited to 50 items.
* **Date Filtering**: Use date filters to improve query performance on large datasets.
* **Indexing**: The API is optimized for filtering by date, user, and evaluation status.
* **Caching**: Consider implementing client-side caching for frequently accessed data.
* **Message Inclusion**: Using `include_messages=true` will increase response size and processing time. The feature uses optimized queries to prevent N+1 issues, but should be used judiciously for large datasets.