Message history

Retrieve and export your thread message analytics data.

Message history

Retrieve and export your thread message analytics data.

Overview

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

This endpoint requires a service account token with the analytics scope. See the Authorization guide 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:

1 {"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:

1 {"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

1 import os
2 import re
3 import requests
4 
5 BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
6 ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
7 
8 def get_filename_from_content_disposition(content_disposition: str) -> str:
9     # Extract filename from Content-Disposition header.
10     match = re.search(r"filename=([^;\s]+)", content_disposition)
11     if match:
12         return match.group(1).strip('"')
13     return "message_history.jsonl"  # fallback
14 
15 
16 headers = {
17     "Authorization": f"Bearer {ACCESS_TOKEN}",
18 }
19 params = {
20     "start_date": "2026-01-01",
21     "end_date": "2026-01-20",
22 }
23 
24 response = requests.get(
25     f"{BASE_URL}/v2/analytics/messages",
26     headers=headers,
27     params=params,
28 )
29 
30 # Get filename from response header
31 content_disposition = response.headers.get("Content-Disposition", "")
32 filename = get_filename_from_content_disposition(content_disposition)
33 
34 with open(filename, "wb") as f:
35     for chunk in response.iter_content(8192):
36         f.write(chunk)

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.

Overview

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

This endpoint requires a service account token with the analytics scope. See the Authorization guide 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:

1 {"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:

1 {"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

1 import os
2 import re
3 import requests
4 
5 BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
6 ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
7 
8 def get_filename_from_content_disposition(content_disposition: str) -> str:
9     # Extract filename from Content-Disposition header.
10     match = re.search(r"filename=([^;\s]+)", content_disposition)
11     if match:
12         return match.group(1).strip('"')
13     return "message_history.jsonl"  # fallback
14 
15 
16 headers = {
17     "Authorization": f"Bearer {ACCESS_TOKEN}",
18 }
19 params = {
20     "start_date": "2026-01-01",
21     "end_date": "2026-01-20",
22 }
23 
24 response = requests.get(
25     f"{BASE_URL}/v2/analytics/messages",
26     headers=headers,
27     params=params,
28 )
29 
30 # Get filename from response header
31 content_disposition = response.headers.get("Content-Disposition", "")
32 filename = get_filename_from_content_disposition(content_disposition)
33 
34 with open(filename, "wb") as f:
35     for chunk in response.iter_content(8192):
36         f.write(chunk)

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.

1	import os
2	import re
3	import requests
4
5	BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
6	ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
7
8	def get_filename_from_content_disposition(content_disposition: str) -> str:
9	# Extract filename from Content-Disposition header.
10	match = re.search(r"filename=([^;\s]+)", content_disposition)
11	if match:
12	return match.group(1).strip('"')
13	return "message_history.jsonl" # fallback
14
15
16	headers = {
17	"Authorization": f"Bearer {ACCESS_TOKEN}",
18	}
19	params = {
20	"start_date": "2026-01-01",
21	"end_date": "2026-01-20",
22	}
23
24	response = requests.get(
25	f"{BASE_URL}/v2/analytics/messages",
26	headers=headers,
27	params=params,
28	)
29
30	# Get filename from response header
31	content_disposition = response.headers.get("Content-Disposition", "")
32	filename = get_filename_from_content_disposition(content_disposition)
33
34	with open(filename, "wb") as f:
35	for chunk in response.iter_content(8192):
36	f.write(chunk)