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

# Reports API

> List reliability reports and run one over a time window: KPIs with the previous window, one chart, and one table.

Reliability reports measure incidents, uptime, MTTR, MTTA, MTTI, response time, on-call escalations,
and issues over a time window. Every report returns the same response shape, so one client can show
every report. See [Reliability reports](/features/reporting) for what each report measures.

## Operations

| Operation | Method and path | Purpose |
| - | - | - |
| `reports.list` | `GET /v1/projects/{project_id}/reports` | List the reports and their sections. |
| `reports.get` | `GET /v1/projects/{project_id}/reports/{report_id}` | Run one report over a window. |

## Report IDs

| Section | `report_id` | Access |
| - | - | - |
| Incidents | `incidents`, `incidents-per-monitor`, `manual-incidents` | `incidents:read` |
| Performance | `mttr`, `mttr-per-monitor`, `mtta`, `mtta-per-monitor`, `mtti` | `incidents:read` |
| Performance | `sla`, `response-time` | `monitors:read` |
| Response | `escalations` | `on_call:read` |
| Errors | `issues` | `errors:read` |
| Infrastructure | `heartbeats` | `monitors:read` |

## Query parameters

| Parameter | Values | Default |
| - | - | - |
| `range` | `7d`, `30d`, `90d`, `mtd` (month to date) | `7d` |
| `from`, `to` | ISO 8601 timestamps. Send both or neither. | Not set. When set, they replace `range`. |
| `granularity` | `hour`, `day`, `week`, `month` | `hour` for 2 days or less, `day` up to 92 days, else `week`. |
| `monitor_id` | A monitor ID | All monitors. Ignored by `manual-incidents` and `issues`. |
| `time_zone` | An IANA time zone, for example `Europe/Berlin` | `UTC` |

* A preset range starts at midnight in `time_zone` and ends now. `7d` is today and the six days
  before it.
* An explicit window can be at most 400 days. A `to` in the future is set to now.
* The previous window has the same length and ends where the window starts.
* `sla` and `heartbeats` always use `UTC` and support only `day`, `week`, and `month`. Each report
  lists its granularities in `report.granularities`.

## Run a report

```bash theme={null}
curl --get \
  --url "https://api.squasher.ai/v1/projects/$SQUASHER_PROJECT_ID/reports/mttr" \
  --header "x-squasher-key: $SQUASHER_API_KEY" \
  --data-urlencode "range=30d" \
  --data-urlencode "time_zone=Europe/Berlin"
```

```json theme={null}
{
  "report": {
    "id": "mttr",
    "section": "performance",
    "title": "MTTR",
    "description": "Mean time to resolve: from an incident opening to its resolution.",
    "granularities": ["day", "week", "month", "hour"],
    "monitor_filter": true,
    "time_zone": null
  },
  "window": {
    "from": "2026-09-07T22:00:00.000Z",
    "to": "2026-10-07T09:30:00.000Z",
    "previous_from": "2026-08-09T10:30:00.000Z",
    "previous_to": "2026-09-07T22:00:00.000Z",
    "granularity": "day",
    "range": "30d",
    "time_zone": "Europe/Berlin"
  },
  "kpis": [
    { "key": "mttr", "label": "MTTR", "unit": "seconds", "value": 1260, "previous": 1835 },
    { "key": "median", "label": "Median", "unit": "seconds", "value": 840, "previous": 990 },
    { "key": "p90", "label": "P90", "unit": "seconds", "value": 3120, "previous": 4410 },
    {
      "key": "reached",
      "label": "Resolved incidents",
      "unit": "count",
      "value": 14,
      "previous": 11
    }
  ],
  "chart": {
    "kind": "line",
    "stacked": false,
    "title": "MTTR per day",
    "unit": "seconds",
    "series": [
      {
        "key": "mttr",
        "label": "MTTR",
        "points": [
          { "bucket": "2026-09-07T22:00:00.000Z", "value": 960 },
          { "bucket": "2026-09-08T22:00:00.000Z", "value": null }
        ]
      }
    ]
  },
  "table": {
    "title": "Resolved incidents, slowest first",
    "columns": [
      {
        "key": "title",
        "label": "Incident",
        "format": "text",
        "link": { "kind": "incident", "id_key": "incident_id" }
      },
      { "key": "time_to", "label": "Time to resolve", "format": "seconds" }
    ],
    "rows": [
      {
        "incident_id": "3f1c2a9e-7b4d-4e1a-9c2f-5d8e6a1b0c34",
        "display_id": "inc_42",
        "title": "API: 500 error rate spike",
        "time_to": 5400
      }
    ],
    "total": 14
  },
  "truncated": false,
  "generated_at": "2026-10-07T09:30:00.000Z"
}
```

The JSON is shortened. A real response has a point for every bucket and more table columns.

## Response fields

| Field | Description |
| - | - |
| `report` | `id`, `section`, `title`, `description`, `granularities`, `monitor_filter`, and `time_zone` (`UTC` for `sla` and `heartbeats`, else `null`). |
| `window` | `from`, `to`, `previous_from`, `previous_to`, `granularity`, `range` (`null` for an explicit window), and `time_zone`. |
| `kpis` | `key`, `label`, `unit`, `value`, and `previous`. `value` or `previous` is `null` when that window has no data for the measure. |
| `chart` | `kind` (`bar`, `line`, or `area`), `stacked`, `title`, `unit`, and `series`. Each series has `key`, `label`, and `points` (`bucket`, `value`). `null` when the report has no chart. |
| `table` | `title`, `columns`, `rows`, and `total`. `rows` has at most 500 rows; `total` is the full row count. |
| `truncated` | `true` when the window held more than 5,000 incidents, pages, or issues. The numbers then cover the first 5,000. |
| `generated_at` | When Squasher ran the report. |

`unit` is `count`, `seconds` (a duration), `percent` (0 to 100), or `milliseconds` (a latency). A
column `format` is a unit, `datetime`, or `text`. When a column has `link`, the row value under
`link.id_key` is the ID of the linked `incident`, `monitor`, or `issue`.

## Errors

| Status | When |
| - | - |
| `400` | `from` without `to`, a window longer than 400 days, an unknown time zone, or a granularity that the report does not support. |
| `403` | The key cannot read the data of the report. See [Report IDs](#report-ids). |
| `404` | The report ID is not known. |

## TypeScript client and CLI

```typescript theme={null}
const catalog = await client.reports.list();
const sla = await client.reports.get("sla", { range: "30d", time_zone: "Europe/Berlin" });
```

```bash theme={null}
squasher reports list --project <project_id>
squasher reports get --project <project_id> sla --range 30d
```

## Related guides

* [Reliability reports](/features/reporting)
* [Incidents API](/api-reference/incidents)
* [On-call API](/api-reference/on-call)
* [Monitors API](/api-reference/monitors)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.