# Funnels

Step-by-step conversion funnels with drop-off between stages.

Source: https://sourceloop.ai/help/api/funnels/

---

| Endpoint | Method | Path | Permission |
| --- | --- | --- | --- |
| Get funnel | GET | `/v1/funnels` | `metrics:read` |

Base URL: `https://app.sourceloop.ai/api/v1`

## Get funnel

`GET /v1/funnels`

Stage-to-stage conversion

Requires scope: `metrics:read`

How many entities entered each stage of a funnel, and the drop-off between
them. Pass `stages` in the order they happen; GET /v1/pipelines lists the
stage vocabulary this workspace uses.

Counted over the WHOLE population, including people the tracker never saw:
imported contacts, deals closed over the phone, customers who predate the
script. That is why these rates are lower than a session-based funnel, and
why they are the honest ones.

These are not a cohort. Somebody counted at a late stage may have entered the
first one before the window, so a step rate above 100% is possible.

To credit a stage to the marketing that produced it, use GET /v1/metrics with
`stages` and an attribution model instead.

### Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `website` | string | no | Website domain, e.g. acme.com. Required only when the key covers more than one. |
| `period` | string | no | Plain-language period: "last 30 days", "yesterday", "July 2026", or "2026-07-01..2026-07-31". Ignored when from/to are given. |
| `stages` | string | yes | Comma-separated stage keys, in funnel order. |

### Responses

- `200` One row per stage
- `400` Something was wrong with the request or the credential.
- `429` Too many requests for this workspace in the current minute. Wait Retry-After seconds and repeat the request unchanged.

### Example (cURL)

```bash
curl -s -X GET "https://app.sourceloop.ai/api/v1/funnels?website=acme.com&period=last%2030%20days&stages=lead%2Cmql%2Ccustomer" \
  -H "Authorization: Bearer $SOURCELOOP_API_KEY"
```

### Example (Node)

```javascript
const res = await fetch(
  "https://app.sourceloop.ai/api/v1/funnels?website=acme.com&period=last%2030%20days&stages=lead%2Cmql%2Ccustomer",
  {
    method: "GET",
    headers: {
      Authorization: `Bearer ${process.env.SOURCELOOP_API_KEY}`,
    },
  },
);

const data = await res.json();
```

### Example (Python)

```python
import os, requests

res = requests.get(
    "https://app.sourceloop.ai/api/v1/funnels?website=acme.com&period=last%2030%20days&stages=lead%2Cmql%2Ccustomer",
    headers={"Authorization": f"Bearer {os.environ['SOURCELOOP_API_KEY']}"},
)
data = res.json()
```