# 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

```http
GET /agents/list
```

Returns all agents belonging to your organization.

### Response

```json
{
  "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

```http
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

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

### Response

```json
{
  "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](https://docs.minded.com/sdk/events#analytics_event) for details.