# Goals and funnels API

> Create, read, update and delete goals and funnels, break a goal down by event property, and run a step-by-step funnel report.

Section: CLI, MCP and API  
Canonical page: https://statsy.co/docs/developers/api-goals-and-funnels  
Last updated: 2026-09-15

Goals and funnels both support the full set of methods. Reads need any role; creating, changing and deleting need owner or editor.

## Goals

| Method and path | Purpose |
| --- | --- |
| `GET /sites/:site/goals` | Lists the site’s goals. |
| `POST /sites/:site/goals` | Creates a goal. Returns 201. |
| `GET /sites/:site/goals/:id` | Reads one goal. |
| `PATCH /sites/:site/goals/:id` | Changes any field. |
| `DELETE /sites/:site/goals/:id` | Deletes it. |
| `GET /sites/:site/goals/:id/breakdown` | Splits conversions by an event property. |

```bash
curl -X POST -H "Authorization: Bearer sta_your_token" \
  -H "Content-Type: application/json" \
  -d '{"name":"Signup","kind":"pageview","match":"path","pattern":"/welcome"}' \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/goals"
```

`kind` is `pageview`, `event`, `click`, `scroll` or `outbound`. `match` is `path` (the default), `wildcard` or `exact`. `pattern` is the path or event name to match, and `valueDefault` optionally gives each conversion a value.

## Breaking a goal down by property

If your goal calls carry properties, `GET /sites/:site/goals/:id/breakdown?prop=plan` groups conversions by one of them. `prop` is required. Rows come back as visitors, conversions and revenue per value, up to `limit` (50 by default, 500 at most).

## Funnels

| Method and path | Purpose |
| --- | --- |
| `GET /sites/:site/funnels` | Lists saved funnels with their steps. |
| `POST /sites/:site/funnels` | Creates a funnel. Returns 201. |
| `GET /sites/:site/funnels/:id` | Reads one funnel. |
| `PATCH /sites/:site/funnels/:id` | Changes the name, steps or window. |
| `DELETE /sites/:site/funnels/:id` | Deletes it. |
| `GET /sites/:site/funnels/:id/report` | Runs the step-by-step report. |

```bash
curl -X POST -H "Authorization: Bearer sta_your_token" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Trial to paid",
    "window": "7d",
    "steps": [
      {"kind": "pageview", "pattern": "/pricing"},
      {"kind": "pageview", "pattern": "/signup"},
      {"kind": "goal", "pattern": "purchase"}
    ]
  }' \
  "https://statsy.co/api/v1/sites/ws_yoursitekey/funnels"
```

A funnel has between two and eight steps, each a `pageview` path or a `goal` name. `window` is how long a visitor has to finish: `30m`, `24h`, `7d` or a number of seconds, anywhere from a minute to 90 days. It defaults to `7d`.

## The funnel report

`GET /sites/:site/funnels/:id/report` takes the usual range and filter parameters, plus an optional `window` that overrides the saved one for this run only. Each step comes back with the visitors who reached it, the drop-off from the step before, and the revenue attached.

> **Tip.** The CLI prints the same report as a table: `statsy funnels report <id> --period 30d`. An AI assistant connected over [MCP](https://statsy.co/docs/developers/mcp) can read it with `get_funnel`.

Previous: [Visitors and journeys API](https://statsy.co/docs/developers/api-visitors)  
Next: [Payment API](https://statsy.co/docs/developers/api-payments)