Reports API — Create, List, and Run Analytics Reports

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

cURL

curl https://api.canoanalytics.io/v1/reports \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

200 OK

{
  "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
}

string

Unique identifier for the report.

string

Human-readable name of the report.

string

The report type. One of event_volume, funnel, retention, or custom.

string

ISO 8601 timestamp of when the report was created.

string

ISO 8601 timestamp of the most recent time this report was executed. null if the report has never been run.

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

string

required

A human-readable name for the report (e.g. "Q3 Retention by Cohort").

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)

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

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

Request example

POST /v1/reports

{
  "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": ["[email protected]", "[email protected]"],
    "format": "pdf"
  }
}

Response — 201 Created

201 Created

{
  "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": ["[email protected]", "[email protected]"],
    "format": "pdf"
  },
  "created_at": "2024-06-15T15:00:00Z",
  "last_run_at": null
}

GET /v1/reports//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

string

required

The unique identifier of the report to run.

Response fields

object

An object containing the report output.

array

An ordered array of column name strings corresponding to each entry in a rows item.

array

An array of data rows. Each row is an array of values aligned with the columns array.

string

ISO 8601 timestamp of when this run completed.

Request example

cURL

curl https://api.canoanalytics.io/v1/reports/rpt_3cZx7wNmBq/run \
  -H "Authorization: Bearer YOUR_API_KEY"

Response — 200 OK

200 OK

{
  "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"
  }
}

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.

Overview

Endpoints

SDKs

Reports API — Create, List, and Run Analytics Reports

GET /v1/reports — List Reports

Request example

Response — 200 OK

POST /v1/reports — Create a Report

Body parameters

Request example

Response — 201 Created

GET /v1/reports//run — Run a Report

Path parameters

Response fields

Request example

Response — 200 OK

​GET /v1/reports — List Reports

​Request example

​Response — 200 OK

​POST /v1/reports — Create a Report

​Body parameters

​Request example

​Response — 201 Created

​GET /v1/reports//run — Run a Report

​Path parameters

​Response fields

​Request example

​Response — 200 OK

GET /v1/reports — List Reports

Request example

Response — 200 OK

POST /v1/reports — Create a Report

Body parameters

Request example

Response — 201 Created

GET /v1/reports//run — Run a Report

Path parameters

Response fields

Request example

Response — 200 OK