Analytics API

Query agent analytics events for dashboards, BI tools, and audits.

Required scope: analytics

Endpoints

Method	Endpoint	Description
GET	/agents/list	List agents in your organization
POST	/events/agent	Query agent analytics events

---

List Agents

GET /agents/list

Returns all agents belonging to your organization.

Response

{
  "success": true,
  "data": [
    {
      "agentId": "agent-uuid-1",
      "displayName": "My Support Agent",
      "createdAt": "2025-10-01T10:30:00.000Z"
    }
  ],
  "count": 1
}

Response Fields

Field	Type	Description
data[].agentId	string	Unique agent identifier
data[].displayName	string	Human-readable agent name
data[].createdAt	string	ISO 8601 creation timestamp
count	number	Total number of agents returned

---

Query Agent Events

POST /events/agent

Query analytics events for a specific agent.

Request Body

Field	Type	Required	Description
agentId	string	Yes	Agent UUID (must belong to your organization)
filters.environment	string	No	development, staging, or production. Default: production
filters.sessionId	string	No	Filter by specific session UUID
filters.eventName	string	No	Filter by event type
filters.startDate	string	No	Start date (ISO 8601)
filters.endDate	string	No	End date (ISO 8601)
limit	number	No	Records per page (1–1000). Default: 100
offset	number	No	Records to skip. Default: 0

Request Example

{
  "agentId": "your-agent-id",
  "filters": {
    "environment": "production",
    "startDate": "2025-10-01T00:00:00Z",
    "endDate": "2025-10-31T23:59:59Z"
  },
  "limit": 100,
  "offset": 0
}

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "agentId": "your-agent-id",
      "sessionId": "session-uuid",
      "environment": "production",
      "eventName": "invocation_start",
      "payload": { ... },
      "created_at": "2025-10-14T08:37:44.000Z"
    }
  ],
  "count": 1,
  "limit": 100,
  "offset": 0
}

Response Fields

Field	Type	Description
data[].id	number	Event record ID
data[].agentId	string	Agent UUID
data[].sessionId	string	Session UUID
data[].environment	string	Environment where event occurred
data[].eventName	string	Event type
data[].payload	object	Event-specific data
data[].created_at	string	ISO 8601 timestamp when event was recorded
count	number	Number of events in current page
limit	number	Page size used
offset	number	Offset used

Event Types

The SDK automatically tracks built-in events. You can also emit custom events.

Built-in events: invocation_start, invocation_error, node_execution, and more.

Custom events: Use trackAnalyticsEvent() from your agent code.

See SDK Events - ANALYTICS_EVENT for details.