> ## Documentation Index
> Fetch the complete documentation index at: https://docs.supersonic.cv/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics

> Aggregate records, analyze pipelines, query the datalake, and generate summaries.

Four analytics tools cover different levels of analysis — from simple record counts to full workspace summaries.

## Tools

| Tool                 | Description                                                | Key Params                                                  |
| -------------------- | ---------------------------------------------------------- | ----------------------------------------------------------- |
| `analytics.records`  | Aggregate records by field values                          | `object_type_slug`, `metrics`, `group_by`, `filters`        |
| `analytics.pipeline` | Pipeline-specific metrics (conversion, velocity)           | `list_id`, `metrics`, `time_range`                          |
| `analytics.datalake` | Query datalake models (activities, emails, meetings, etc.) | `model`, `metrics`, `group_by`, `time_range`, `time_bucket` |
| `analytics.summary`  | High-level workspace summary                               | `time_range`                                                |

### Metrics

| Metric              | Description                                            |
| ------------------- | ------------------------------------------------------ |
| `count`             | Number of records                                      |
| `sum`               | Sum of a numeric field                                 |
| `avg`               | Average of a numeric field                             |
| `min` / `max`       | Min/max of a field                                     |
| `conversion_rate`   | Percentage that reached a target stage (pipeline only) |
| `avg_time_in_stage` | Average days in each stage (pipeline only)             |
| `velocity`          | Average days from entry to close (pipeline only)       |

### Time Buckets

`day` `week` `month` `quarter` `year`

## Examples

### Count deals by stage

```json theme={null}
{
  "tool": "analytics.records",
  "params": {
    "object_type_slug": "deals",
    "metrics": ["count", "sum"],
    "group_by": "Stage",
    "filters": [
      { "field": "Stage", "operator": "not_in", "value": ["Closed Lost"] }
    ]
  }
}
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "groups": [
      { "Stage": "Qualified", "count": 12, "sum_Deal Value": 340000 },
      { "Stage": "Proposal Sent", "count": 8, "sum_Deal Value": 520000 },
      { "Stage": "Negotiation", "count": 5, "sum_Deal Value": 410000 },
      { "Stage": "Closed Won", "count": 15, "sum_Deal Value": 1250000 }
    ]
  }
}
```

### Get pipeline conversion metrics

```json theme={null}
{
  "tool": "analytics.pipeline",
  "params": {
    "list_id": "lst_abc123",
    "metrics": ["conversion_rate", "velocity", "avg_time_in_stage"],
    "time_range": {
      "start": "2026-01-01",
      "end": "2026-03-23"
    }
  }
}
```

### Query datalake — emails per week

```json theme={null}
{
  "tool": "analytics.datalake",
  "params": {
    "model": "communication",
    "metrics": ["count"],
    "group_by": "direction",
    "time_range": {
      "start": "2026-01-01",
      "end": "2026-03-23"
    },
    "time_bucket": "week"
  }
}
```

### Workspace summary

```json theme={null}
{
  "tool": "analytics.summary",
  "params": {
    "time_range": {
      "start": "2026-03-01",
      "end": "2026-03-23"
    }
  }
}
```