> ## 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.

# Reports

> Create, manage, and execute saved reports with charts and filters.

Reports are saved analytics queries with visualization config. Define the data source, metrics, grouping, filters, and chart type — then execute on demand or display in dashboards.

## Tools

| Tool              | Description                  | Key Params                                    |
| ----------------- | ---------------------------- | --------------------------------------------- |
| `reports.list`    | List all saved reports       | —                                             |
| `reports.get`     | Get a report's configuration | `report_id`                                   |
| `reports.create`  | Create a new report          | `name`, `config`                              |
| `reports.update`  | Update a report's config     | `report_id`, `name`, `config`                 |
| `reports.delete`  | Delete a report              | `report_id`                                   |
| `reports.execute` | Run a report and return data | `report_id`, `time_range` (optional override) |

### Config Structure

| Field              | Description                                       |
| ------------------ | ------------------------------------------------- |
| `object_type_slug` | Which object type to query                        |
| `list_id`          | Optional — scope to a specific pipeline/list      |
| `metric`           | `count`, `sum`, `avg`, `min`, `max`               |
| `metric_field`     | Field to aggregate (required for sum/avg/min/max) |
| `group_by`         | Field to group results by                         |
| `chart_type`       | `bar`, `line`, `pie`, `number`, `table`           |
| `filters`          | Array of filter objects                           |
| `time_range`       | Default time range                                |

## Examples

### Create a bar chart of deals by stage

```json theme={null}
{
  "tool": "reports.create",
  "params": {
    "name": "Deals by Stage",
    "config": {
      "object_type_slug": "deals",
      "list_id": "lst_abc123",
      "metric": "sum",
      "metric_field": "Deal Value",
      "group_by": "Stage",
      "chart_type": "bar",
      "filters": [
        { "field": "Stage", "operator": "not_in", "value": ["Closed Lost"] }
      ],
      "time_range": {
        "start": "2026-01-01",
        "end": "2026-03-23"
      }
    }
  }
}
```

### Execute a report

```json theme={null}
{
  "tool": "reports.execute",
  "params": {
    "report_id": "rpt_001"
  }
}
```

Response:

```json theme={null}
{
  "success": true,
  "data": {
    "chart_type": "bar",
    "labels": ["Qualified", "Proposal Sent", "Negotiation", "Closed Won"],
    "datasets": [
      {
        "label": "Deal Value (sum)",
        "data": [340000, 520000, 410000, 1250000]
      }
    ]
  }
}
```

### Create a line chart tracking new contacts over time

```json theme={null}
{
  "tool": "reports.create",
  "params": {
    "name": "New Contacts per Week",
    "config": {
      "object_type_slug": "contacts",
      "metric": "count",
      "group_by": "created_at",
      "chart_type": "line",
      "time_range": {
        "start": "2026-01-01",
        "end": "2026-03-23"
      }
    }
  }
}
```