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

# Dashboards API — List and Retrieve Your Dashboards

> Use the Dashboards API to list all dashboards in your workspace and retrieve full dashboard metadata including charts, filters, and public share URLs.

The Dashboards API lets you list and retrieve dashboard metadata programmatically — useful for building internal portals, embedding dashboard links in other tools, or auditing your workspace's dashboards without logging into the Cano Analytics UI. All requests require the **read** scope.

***

## GET /v1/dashboards — List Dashboards

Retrieve a paginated list of all dashboards in your workspace.

### Query parameters

<ParamField query="limit" type="integer">
  Number of dashboards to return per page. Defaults to `50`. Maximum is `200`.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque pagination cursor from the previous response's `next_cursor` field.
</ParamField>

### Request example

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

### Response — 200 OK

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "dsh_8bYc3kPmNz",
      "name": "Growth Overview",
      "created_at": "2024-02-01T10:00:00Z",
      "updated_at": "2024-06-14T09:15:33Z",
      "chart_count": 6
    },
    {
      "id": "dsh_2aXr9hQeLw",
      "name": "Activation Funnel",
      "created_at": "2024-03-12T14:22:00Z",
      "updated_at": "2024-06-10T17:45:00Z",
      "chart_count": 3
    }
  ],
  "next_cursor": null,
  "has_more": false
}
```

<ResponseField name="data" type="array">
  An array of dashboard summary objects.
</ResponseField>

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

<ResponseField name="data[].name" type="string">
  Human-readable name of the dashboard as it appears in the UI.
</ResponseField>

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

<ResponseField name="data[].updated_at" type="string">
  ISO 8601 timestamp of the most recent change to the dashboard.
</ResponseField>

<ResponseField name="data[].chart_count" type="integer">
  Number of charts currently on the dashboard.
</ResponseField>

***

## GET /v1/dashboards/{id} — Get a Dashboard

Retrieve the complete metadata for a single dashboard, including the full list of charts and their configurations.

### Path parameters

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

### Response fields

<ResponseField name="id" type="string">
  Unique identifier for the dashboard.
</ResponseField>

<ResponseField name="name" type="string">
  Human-readable name of the dashboard.
</ResponseField>

<ResponseField name="description" type="string">
  Optional description of the dashboard's purpose.
</ResponseField>

<ResponseField name="charts" type="array">
  An array of chart objects belonging to this dashboard. See chart fields below.
</ResponseField>

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

<ResponseField name="charts[].title" type="string">
  Display title of the chart.
</ResponseField>

<ResponseField name="charts[].type" type="string">
  Chart visualization type. Examples: `line`, `bar`, `pie`, `funnel`, `table`.
</ResponseField>

<ResponseField name="charts[].event" type="string">
  The event name this chart is based on.
</ResponseField>

<ResponseField name="charts[].filters" type="array">
  An array of filter objects applied to the chart (e.g. `{ "property": "plan", "operator": "eq", "value": "pro" }`).
</ResponseField>

<ResponseField name="charts[].group_by" type="string">
  The property used to group or segment the chart's data (e.g. `"plan"`, `"country"`).
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the dashboard was created.
</ResponseField>

<ResponseField name="updated_at" type="string">
  ISO 8601 timestamp of the most recent change to the dashboard.
</ResponseField>

<ResponseField name="public_url" type="string">
  A shareable public URL for this dashboard, if public sharing is enabled. `null` if the dashboard is private.
</ResponseField>

### Request example

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

### Response — 200 OK

```json 200 OK theme={null}
{
  "id": "dsh_8bYc3kPmNz",
  "name": "Growth Overview",
  "description": "Top-level metrics for acquisition, activation, and retention.",
  "charts": [
    {
      "id": "chrt_1aQp7mVcLx",
      "title": "Daily Sign-ups by Plan",
      "type": "bar",
      "event": "signup_completed",
      "filters": [],
      "group_by": "plan"
    },
    {
      "id": "chrt_5fNk2rBwYj",
      "title": "Revenue Over Time (Pro Users)",
      "type": "line",
      "event": "order_completed",
      "filters": [
        {
          "property": "plan",
          "operator": "eq",
          "value": "pro"
        }
      ],
      "group_by": null
    }
  ],
  "created_at": "2024-02-01T10:00:00Z",
  "updated_at": "2024-06-14T09:15:33Z",
  "public_url": "https://app.canoanalytics.io/public/dashboards/dsh_8bYc3kPmNz"
}
```

<Tip>
  Use `public_url` to embed a read-only dashboard link in internal wikis or customer-facing status pages without requiring recipients to have a Cano Analytics account.
</Tip>