Sessions API
Use the Sessions API to retrieve session history and message logs from your UsageGuard reverse-proxy application. These endpoints allow you to access conversation data for analysis, debugging, and compliance purposes.
Get Session History
Retrieve a paginated list of sessions with optional filtering by end user and date range. Use this to browse conversation sessions and their metadata.
Request Headers
- Name
Authorization- Type
- string
- Description
Bearer token for authentication. Format: 'Bearer your-token-here'
- Name
Content-Type- Type
- string
- Description
application/json
Request Body
- Name
end_user_id- Type
- string
- Description
Filter sessions by specific end user identifier
- Name
date_from- Type
- string
- Description
Start date for filtering in ISO format (e.g., "2023-06-15T00:00:00Z")
- Name
date_to- Type
- string
- Description
End date for filtering in ISO format (e.g., "2023-06-15T23:59:59Z")
- Name
from- Type
- integer
- Description
Pagination start index (default: 1)
- Name
size- Type
- integer
- Description
Number of sessions per page (default: 100)
- Name
sort_ascending- Type
- boolean
- Description
Sort order - true for ascending, false for descending by date (default: false)
Request
curl -X POST https://api.usageguard.com/v1/management/reporting/sessions/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"end_user_id": "user_12345",
"date_from": "2023-06-15T00:00:00Z",
"date_to": "2023-06-15T23:59:59Z",
"from": 1,
"size": 100,
"sort_ascending": false
}'
Response
{
"sessions": [
{
"schema": "sessions.history.entry.v1",
"version": "1.0",
"end_user_id": "user_12345",
"session_id": "sess_a1b2c3d4e5f6",
"title": "Product Feature Discussion",
"created_at": "2023-06-15T10:30:00Z",
"updated_at": "2023-06-15T11:45:00Z"
}
],
"total": 1
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid date format. Use ISO 8601 format (YYYY-MM-DDTHH:mm:ssZ)"
}
401: Unauthorized
{
"error": "Unauthorized",
"message": "Invalid or expired token"
}
500: Server Error
{
"error": "Internal Server Error",
"message": "An unexpected error occurred while retrieving session history"
}
Get Message History
Retrieve detailed message history for a specific session or across multiple sessions. Use this to access individual conversation messages with full context including input/output text, timestamps, and metadata.
Request Headers
- Name
Authorization- Type
- string
- Description
Bearer token for authentication. Format: 'Bearer your-token-here'
- Name
Content-Type- Type
- string
- Description
application/json
Request Body
- Name
session_id- Type
- string
- Description
Filter messages by specific session identifier
- Name
connection_id- Type
- string
- Description
Filter messages by specific connection identifier
- Name
end_user_id- Type
- string
- Description
Filter messages by specific end user identifier
- Name
date_from- Type
- string
- Description
Start date for filtering in ISO format (e.g., "2023-06-15T00:00:00Z")
- Name
date_to- Type
- string
- Description
End date for filtering in ISO format (e.g., "2023-06-15T23:59:59Z")
- Name
from- Type
- integer
- Description
Pagination start index (default: 1)
- Name
size- Type
- integer
- Description
Number of messages per page (default: 100)
- Name
sort_ascending- Type
- boolean
- Description
Sort order - true for ascending, false for descending by date (default: true)
Request
curl -X POST https://api.usageguard.com/v1/management/reporting/messages/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_a1b2c3d4e5f6",
"connection_id": "conn_7890xyz",
"end_user_id": "user_12345",
"date_from": "2023-06-15T00:00:00Z",
"date_to": "2023-06-15T23:59:59Z",
"from": 1,
"size": 100,
"sort_ascending": true
}'
Response
{
"messages": [
{
"schema": "messages.history.entry.v1",
"version": "2.0",
"trace_id": "66c272587798ea7fd68cef759386fc44",
"end_user_id": "custom-user-name-01",
"session_id": "d9fedd84-1940-42b0-9ed9-4ad9ee666964",
"connection_id": "l5v0b3eyj8",
"input_text": "What would be a great feature to add to the product (AI Development platform)? short answer",
"output_text": "Integrated Auto-ML tools for automated model selection, hyperparameter tuning, and deployment, making AI development accessible to non-experts while saving time.",
"remote_ip_address": "::1",
"user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36",
"created_at": "2025-09-04T07:15:44.2830600Z"
}
],
"total": 1
}
400: Bad Request
{
"error": "Bad Request",
"message": "Invalid request parameters. At least one filter parameter must be provided."
}
401: Unauthorized
{
"error": "Unauthorized",
"message": "Invalid or expired token"
}
403: Forbidden
{
"error": "Forbidden",
"message": "Insufficient permissions to access message history"
}
500: Server Error
{
"error": "Internal Server Error",
"message": "An unexpected error occurred while retrieving message history"
}
Response Schema Details
Session History Entry
- Name
schema- Type
- string
- Description
Schema version identifier for the session entry
- Name
version- Type
- string
- Description
Version of the session data format
- Name
end_user_id- Type
- string
- Description
Unique identifier for the end user who created the session
- Name
session_id- Type
- string
- Description
Unique identifier for the session
- Name
title- Type
- string
- Description
Human-readable title or description of the session
- Name
created_at- Type
- dateTimeOffset
- Description
ISO 8601 timestamp when the session was created
- Name
updated_at- Type
- dateTimeOffset
- Description
ISO 8601 timestamp when the session was last updated
Message History Entry
- Name
schema- Type
- string
- Description
Schema version identifier for the message entry
- Name
version- Type
- string
- Description
Version of the message data format
- Name
trace_id- Type
- string
- Description
Unique trace identifier for distributed tracing
- Name
end_user_id- Type
- string
- Description
Unique identifier for the end user who sent the message
- Name
session_id- Type
- string
- Description
Unique identifier for the session containing this message
- Name
connection_id- Type
- string
- Description
Unique identifier for the connection used for this message
- Name
input_text- Type
- string
- Description
The user's input message or prompt
- Name
output_text- Type
- string
- Description
The AI model's response or output
- Name
remote_ip_address- Type
- string
- Description
IP address of the client who sent the request
- Name
user_agent- Type
- string
- Description
User agent string from the client's browser or application
- Name
created_at- Type
- dateTimeOffset
- Description
ISO 8601 timestamp when the message was created
Usage Examples
Filtering Sessions by Date Range
curl -X POST https://api.usageguard.com/v1/management/reporting/sessions/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"date_from": "2023-06-01T00:00:00Z",
"date_to": "2023-06-30T23:59:59Z",
"size": 50
}'
Getting Messages for a Specific Session
curl -X POST https://api.usageguard.com/v1/management/reporting/messages/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"session_id": "sess_a1b2c3d4e5f6",
"sort_ascending": true
}'
Pagination Example
# Get first page
curl -X POST https://api.usageguard.com/v1/management/reporting/sessions/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"from": 1,
"size": 25
}'
# Get second page
curl -X POST https://api.usageguard.com/v1/management/reporting/sessions/history \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"from": 26,
"size": 25
}'
Best Practices
-
Use appropriate date ranges: Limit your queries to reasonable date ranges to avoid timeouts and improve performance.
-
Implement pagination: For large datasets, use the
fromandsizeparameters to implement proper pagination. -
Filter efficiently: Use specific filters like
session_idorend_user_idto narrow down results when possible. -
Handle rate limits: These endpoints may have rate limits. Implement appropriate retry logic with exponential backoff.
-
Secure your tokens: Always use HTTPS and keep your authentication tokens secure. Never expose them in client-side code.
Error Handling
The Sessions API returns standard HTTP status codes:
- 200 OK: Request successful
- 400 Bad Request: Invalid request parameters or malformed JSON
- 401 Unauthorized: Missing or invalid authentication token
- 403 Forbidden: Insufficient permissions to access the requested data
- 429 Too Many Requests: Rate limit exceeded
- 500 Internal Server Error: Server-side error occurred
Always check the response status code and handle errors appropriately in your application.