> This page is for Alfa (Preview).

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.alfa.boosted.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.alfa.boosted.ai/_mcp/server.

# Message history

## Overview

The Message History endpoint allows you to export all thread messages and their responses as a JSONL (JSON Lines) file.

> **Note**
>
> This endpoint requires a service account token with the `analytics` scope. See the [Authorization guide](/alfa-preview/authorization) for details on obtaining a service account token.

## Endpoint

```
GET {BASE_URL}/v2/analytics/messages
```

## Query parameters

| Parameter    | Type              | Description                                                                       |
| ------------ | ----------------- | --------------------------------------------------------------------------------- |
| `start_date` | string (optional) | Start date for the analytics query (UTC 00:00:00 inclusive). Format: `YYYY-MM-DD` |
| `end_date`   | string (optional) | End date for the analytics query (UTC 23:59:59 inclusive). Format: `YYYY-MM-DD`   |

### Date filtering behavior

* If `start_date` is not provided, returns all messages on and before the `end_date` (UTC 23:59:59)
* If `end_date` is not provided, returns all messages on and after the `start_date` (UTC 00:00:00)
* If both dates are not provided, returns all messages

## Response format

The endpoint returns a streamed JSONL file with each line having the following structure:

```json
{"Input":"<user_message>","Response":"<assistant_response>","Message ID":"<message_id>","Message Time":"<iso_timestamp>","Thread ID":"<thread_id>","User ID":"<user_id>"}
```

If an error occurs during the streaming process, the final line in the file will have the following structure:

```json
{"error": true, "message": "Streaming error: RuntimeError"}
```

### Response fields

| Field          | Type   | Description                                                                                 |
| -------------- | ------ | ------------------------------------------------------------------------------------------- |
| `Input`        | string | The user's input message                                                                    |
| `Response`     | string | The assistant's response message                                                            |
| `Message ID`   | string | Unique identifier for the message                                                           |
| `Message Time` | string | ISO 8601 timestamp of when the message was sent Example: `2025-09-25T18:09:49.014954+00:00` |
| `Thread ID`    | string | Unique identifier for the thread                                                            |
| `User ID`      | string | Unique identifier for the user                                                              |

## Important Notes

The messages provided by this endpoint will be on a 1 day delay, meaning it will not be able to fetch message history for messages made on the same day.

## Example usage

**`export_messages.py`**

```python title="export_messages.py"
import os
import re
import requests

BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]

def get_filename_from_content_disposition(content_disposition: str) -> str:
    # Extract filename from Content-Disposition header.
    match = re.search(r"filename=([^;\s]+)", content_disposition)
    if match:
        return match.group(1).strip('"')
    return "message_history.jsonl"  # fallback


headers = {
    "Authorization": f"Bearer {ACCESS_TOKEN}",
}
params = {
    "start_date": "2026-01-01",
    "end_date": "2026-01-20",
}

response = requests.get(
    f"{BASE_URL}/v2/analytics/messages",
    headers=headers,
    params=params,
)

# Get filename from response header
content_disposition = response.headers.get("Content-Disposition", "")
filename = get_filename_from_content_disposition(content_disposition)

with open(filename, "wb") as f:
    for chunk in response.iter_content(8192):
        f.write(chunk)
```

**`export_messages.sh`**

```bash title="export_messages.sh"
curl -X GET "https://sandbox.api.boosted.ai/v2/analytics/messages?start_date=2026-01-01&end_date=2026-01-20" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -o message_history.jsonl
```

> **Warning**
>
> The JSONL format requires one JSON object per line. Each line must be valid JSON, but the file as a whole is not a JSON array.

## FAQ

#### What is the maximum date range I can query?

There is no hard limit on the date range, but larger date ranges will take longer to process
and return larger files. Consider breaking up very large date ranges into smaller chunks.