# Insights

<Callout type="warning">
  Insights is currently in beta. The API surface and dashboard features may change as development continues.
</Callout>

Gram Insights provides observability for AI tool usage across deployments. Track tool calls, analyze chat sessions, and monitor performance metrics—all in one place.

## Features

- **[Logs](/docs/mcp/observe/insights/logs)** - Search and explore tool call traces with OpenTelemetry-compatible log records
- **[Metrics](/docs/mcp/observe/insights/metrics)** - View aggregated statistics like token usage, success rates, and popular tools

## Accessing Insights

Insights is available in the Gram dashboard. Navigate to a project and select **Logs** or **Metrics** from the sidebar.

The Insights API endpoints are also available for programmatic access. All endpoints are part of the Gram OpenAPI specification at [app.getgram.ai/openapi.yaml](https://app.getgram.ai/openapi.yaml).

## Authentication

### Dashboard

Log in to [app.getgram.ai](https://app.getgram.ai) to access Insights through the dashboard interface.

### API

API requests require authentication headers:

| Header | Description |
| ------ | ----------- |
| `Gram-Key` | API key with `Consumer` or `Producer` scope |
| `Gram-Project` | Project identifier (slug) |

```bash
curl -X POST "https://app.getgram.ai/rpc/telemetry.searchLogs" \
  -H "Content-Type: application/json" \
  -H "Gram-Key: <your-api-key>" \
  -H "Gram-Project: <your-project-slug>" \
  -d '{"limit": 50}'
```

## User-level filtering

Insights supports filtering data by user identity. Pass a `user_id` or `external_user_id` when making tool calls to enable per-user analytics.

This allows:
- Filtering logs and chats by specific users
- Viewing metrics aggregated per user
- Debugging issues for individual users

See the [Logs](/docs/mcp/observe/insights/logs) and [Metrics](/docs/mcp/observe/insights/metrics) documentation for filter parameter details.