Usage & Analytics

Monitor system utilization, track session performance, and analyze interaction traces. These endpoints provide granular visibility into how your application consumes resources.

Analytics Scope

Analytics data includes LLM token usage, database operations (Vector/Graph/SQL), and agent execution steps. Data is aggregated in near real-time.

GET

/api/analytics/usage/summary

Retrieve aggregated usage statistics broken down by event type (e.g., LLM calls, DB operations). Useful for building internal dashboards or monitoring system load.

Query Parameters

Parameter	Type	Required	Description
`start_date`	string	No	Filter start date (ISO 8601)
`end_date`	string	No	Filter end date (ISO 8601)
`user_id`	string	No	Filter by specific user ID
`tenant_id`	string	No	Filter by tenant ID (multi-tenant setups)

GET

/api/analytics/usage/sessions

Get high-level analytics for user sessions, including duration, turn count, and total token consumption.

GET

/api/analytics/trace/{trace_id}

Retrieve the full "waterfall" of events for a specific request trace. This includes every sub-step (LLM call, DB query, Agent action) associated with a single API request.

cURL Example

curl -X GET https://your-api.com/api/analytics/trace/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-Key: your-api-key"

POST

/api/benchmarks/run

Trigger a synchronous A/B benchmark to measure the impact of the memory system on a specific query. Runs the query with and without memory context and compares the results using LLM-as-a-Judge.

cURL Example

curl -X POST https://your-api.com/api/benchmarks/run \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What details do you remember about my project?",
    "user_id": "user_123"
  }'