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

# Reports API — Create, List, and Run Analytics Reports

> Use the Reports API to list saved reports, create new ones with custom schedules, and trigger on-demand runs that return structured result data.

The Reports API lets you create, list, and manage saved analytics reports in Cano Analytics. You can define one-off or scheduled reports — with results delivered by email as PDF or CSV — and trigger immediate runs to retrieve structured data programmatically. Use this API to power custom reporting workflows or automate data delivery to stakeholders.

***

## GET /v1/reports — List Reports

Retrieve all saved reports in your workspace. This endpoint requires the **read** scope.

### Request example

```bash cURL theme={null}
curl https://api.canoanalytics.io/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response — 200 OK

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "rpt_3cZx7wNmBq",
      "name": "Weekly Activation Funnel",
      "type": "funnel",
      "created_at": "2024-03-05T11:00:00Z",
      "last_run_at": "2024-06-14T08:00:01Z"
    },
    {
      "id": "rpt_9jLp2kYdFv",
      "name": "Monthly Event Volume",
      "type": "event_volume",
      "created_at": "2024-01-20T09:30:00Z",
      "last_run_at": "2024-06-01T08:00:03Z"
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

<ResponseField name="data[].id" type="string">
  Unique identifier for the report.
</ResponseField>

<ResponseField name="data[].name" type="string">
  Human-readable name of the report.
</ResponseField>

<ResponseField name="data[].type" type="string">
  The report type. One of `event_volume`, `funnel`, `retention`, or `custom`.
</ResponseField>

<ResponseField name="data[].created_at" type="string">
  ISO 8601 timestamp of when the report was created.
</ResponseField>

<ResponseField name="data[].last_run_at" type="string">
  ISO 8601 timestamp of the most recent time this report was executed. `null` if the report has never been run.
</ResponseField>

***

## POST /v1/reports — Create a Report

Create a new saved report with an optional recurring delivery schedule. This endpoint requires the **write** scope.

### Body parameters

<ParamField body="name" type="string" required>
  A human-readable name for the report (e.g. `"Q3 Retention by Cohort"`).
</ParamField>

<ParamField body="type" type="string" required>
  The analysis type. Must be one of:

  * `event_volume` — total occurrences of events over time
  * `funnel` — conversion rates through an ordered sequence of events
  * `retention` — percentage of users who return after an initial event
  * `custom` — arbitrary SQL or saved query (available on Enterprise plans)
</ParamField>

<ParamField body="config" type="object" required>
  Configuration object defining what the report analyzes. Fields vary by `type` but typically include:

  * `events` (array of strings) — event names to include
  * `from` (string) — ISO 8601 start date for the report window
  * `to` (string) — ISO 8601 end date for the report window
  * `group_by` (string) — a user trait or event property to segment results by
</ParamField>

<ParamField body="schedule" type="object">
  Optional recurring delivery configuration. When provided, Cano Analytics automatically runs the report and emails results on the defined cadence.

  * `frequency` (string) — how often to run the report: `daily`, `weekly`, or `monthly`
  * `recipients` (array of strings) — list of email addresses to deliver results to
  * `format` (string) — delivery format: `pdf` or `csv`
</ParamField>

### Request example

```json POST /v1/reports theme={null}
{
  "name": "Weekly Activation Funnel",
  "type": "funnel",
  "config": {
    "events": ["signup_completed", "onboarding_finished", "first_dashboard_created"],
    "from": "2024-06-01T00:00:00Z",
    "to": "2024-06-30T23:59:59Z",
    "group_by": "plan"
  },
  "schedule": {
    "frequency": "weekly",
    "recipients": ["analytics@example.com", "ceo@example.com"],
    "format": "pdf"
  }
}
```

### Response — 201 Created

```json 201 Created theme={null}
{
  "id": "rpt_3cZx7wNmBq",
  "name": "Weekly Activation Funnel",
  "type": "funnel",
  "config": {
    "events": ["signup_completed", "onboarding_finished", "first_dashboard_created"],
    "from": "2024-06-01T00:00:00Z",
    "to": "2024-06-30T23:59:59Z",
    "group_by": "plan"
  },
  "schedule": {
    "frequency": "weekly",
    "recipients": ["analytics@example.com", "ceo@example.com"],
    "format": "pdf"
  },
  "created_at": "2024-06-15T15:00:00Z",
  "last_run_at": null
}
```

***

## GET /v1/reports/{id}/run — Run a Report

Trigger an immediate, synchronous execution of a saved report and retrieve the results in the response. This is useful for on-demand data pulls or testing a report's configuration. This endpoint requires the **read** scope.

### Path parameters

<ParamField path="id" type="string" required>
  The unique identifier of the report to run.
</ParamField>

### Response fields

<ResponseField name="result" type="object">
  An object containing the report output.
</ResponseField>

<ResponseField name="result.columns" type="array">
  An ordered array of column name strings corresponding to each entry in a `rows` item.
</ResponseField>

<ResponseField name="result.rows" type="array">
  An array of data rows. Each row is an array of values aligned with the `columns` array.
</ResponseField>

<ResponseField name="result.generated_at" type="string">
  ISO 8601 timestamp of when this run completed.
</ResponseField>

### Request example

```bash cURL theme={null}
curl https://api.canoanalytics.io/v1/reports/rpt_3cZx7wNmBq/run \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response — 200 OK

```json 200 OK theme={null}
{
  "result": {
    "columns": ["step", "plan", "users", "conversion_rate"],
    "rows": [
      ["signup_completed",          "pro",  1240, 1.00],
      ["onboarding_finished",       "pro",   983, 0.79],
      ["first_dashboard_created",   "pro",   701, 0.57],
      ["signup_completed",          "free", 4810, 1.00],
      ["onboarding_finished",       "free", 2104, 0.44],
      ["first_dashboard_created",   "free",  876, 0.18]
    ],
    "generated_at": "2024-06-15T15:02:44.891Z"
  }
}
```

<Info>
  For large reports, run time may take several seconds. If your report consistently times out, consider narrowing the date range in `config` or using the scheduled delivery feature instead.
</Info>