Source: https://datafa.st/docs/api/website/analytics/funnel-results
Markdown source: https://datafa.st/docs/api/website/analytics/funnel-results.md
Description: Return step-by-step conversion analytics for one active funnel — visitors per step, drop-off, revenue, and overall conversion rate. Create funnels with [Create funnel](/docs/api-admin-create-funnel), then query results here.

# Get funnel analytics

`GET https://datafa.st/api/v1/analytics/funnels/{funnelId}`

Return step-by-step conversion analytics for one active funnel — visitors per step, drop-off, revenue, and overall conversion rate. Create funnels with [Create funnel](/docs/api/account/funnels/create), then query results here.

Omit `startAt` and `endAt` for all-time funnel data. Inactive (soft-deleted) funnels return **404**.

> **Related:** [Conversion funnels](/docs/conversion-funnels) · [Funnel analytics](/docs/api/website/analytics/funnel-results)

## Request

#### Path parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `funnelId` | string | — | Funnel ObjectId from [List funnels](/docs/api/account/funnels/list). Must be active. Create via [Create funnel](/docs/api/account/funnels/create). |

#### Query parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `websiteId` | string | Required with dft_ | Required with a `dft_` account token on Website API routes. Omit with a `df_` website key. Example: `?websiteId=665f0b3c4d2e1a0012345678`. |
| `startAt` | string | No* | Start of the reporting window. Use `YYYY-MM-DD` for calendar days or an ISO timestamp. Must be provided together with `endAt`. Example: `startAt=2026-05-01`. |
| `endAt` | string | No* | End of the reporting window. Must be provided together with `startAt`. Example: `endAt=2026-05-21`. |
| `timezone` | string | No | Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. IANA timezone for dashboard periods and API date grouping. Examples: `"America/New_York"`, `"Europe/Paris"`, `"UTC"`. Defaults to the website timezone when omitted. |
| `filter_country` | string | No | Limit results to one or more countries. Prefix with an operator: `is`, `is_not`. Accepts country names or codes. Example: `filter_country=US,Canada` or `filter_country=is_not:France`. |
| `filter_region` | string | No | Limit results by region or state. Example: `filter_region=California`. |
| `filter_city` | string | No | Limit results by city. Example: `filter_city=San Francisco`. |
| `filter_device` | string | No | Limit results by device type: `desktop`, `mobile`, or `tablet`. Example: `filter_device=mobile`. |
| `filter_browser` | string | No | Limit results by browser. Filtering `Safari` also includes Mobile Safari. Example: `filter_browser=Chrome,Safari`. |
| `filter_os` | string | No | Limit results by operating system. Example: `filter_os=iOS,Android`. |
| `filter_referrer` | string | No | Limit results by referrer domain or normalized source such as `Google` or `Direct/None`. Example: `filter_referrer=Google`. |
| `filter_page` | string | No | Limit results to visitors who viewed a page. Operators: `is`, `is_not`, `contains`, `does_not_contain`. Example: `filter_page=contains:/docs`. |
| `filter_entry_page` | string | No | Limit results by first page in the session. Same operators as `filter_page`. Example: `filter_entry_page=/pricing`. |
| `filter_hostname` | string | No | Limit results by tracked hostname. Example: `filter_hostname=app.example.com`. |
| `filter_goal` | string | No | Limit results to visitors who completed a goal. Example: `filter_goal=signup`. |
| `filter_utm_source` | string | No | Limit results by UTM source. Example: `filter_utm_source=google`. |
| `filter_utm_medium` | string | No | Limit results by UTM medium. Example: `filter_utm_medium=cpc`. |
| `filter_utm_campaign` | string | No | Limit results by UTM campaign. Example: `filter_utm_campaign=launch`. |
| `filter_utm_term` | string | No | Limit results by UTM term. Example: `filter_utm_term=brand-keyword`. |
| `filter_utm_content` | string | No | Limit results by UTM content. Example: `filter_utm_content=hero-cta`. |
| `filter_ref` | string | No | Limit results by the `ref` URL parameter. Example: `filter_ref=twitter`. |
| `filter_source` | string | No | Limit results by the `source` URL parameter. Example: `filter_source=newsletter`. |
| `filter_via` | string | No | Limit results by the `via` URL parameter. Example: `filter_via=partner`. |

#### Example request

```http
GET /api/v1/analytics/funnels/665f0b3c4d2e1a0012345678?startAt=2026-05-01&endAt=2026-05-21
```

## Response

Returns a JSON object with `status: "success"` and endpoint-specific fields in `data` (and `pagination` when the endpoint is paginated).

#### Response fields

| Field | Type | Description |
| --- | --- | --- |
| `data[].funnel.id` | string | Funnel ObjectId. |
| `data[].funnel.name` | string | Human-readable name for the resource or event. The exact meaning depends on the endpoint. |
| `data[].funnel.slug` | string | Funnel slug. |
| `data[].funnel.steps` | object[] | Configured funnel steps used for matching. |
| `data[].data[].id` | string | Step ID. |
| `data[].data[].label` | string | Step label shown in reports. |
| `data[].data[].value` | number | Visitors who reached this step. |
| `data[].data[].revenue` | number | Revenue attributed to this row or time bucket, in the website currency. Use it to see which time periods or dimensions influenced paid conversions. Revenue attributed to visitors who reached this step. |
| `data[].data[].conversionRate` | number | Percent of first-step visitors who reached this step. |
| `data[].data[].dropoffFromPrevious` | number | Visitors lost compared with the previous step. |
| `data[].metrics.totalVisitors` | number | Visitors who reached the first funnel step. |
| `data[].metrics.completions` | number | Number of times this goal was completed. This counts events, so one visitor can contribute more than one completion. |
| `data[].metrics.overallConversionRate` | number | Percent of first-step visitors who completed the funnel. |
| `data[].metrics.overallRevenuePerVisitor` | number | Revenue divided by first-step visitors. |
| `data[].metrics.timezone` | string | Timezone used to interpret dates and group analytics buckets. Defaults to the website timezone. |
| `data[].metrics.startAt` | string\|null | Start of the reporting window. Use it with `endAt` to query a specific date range instead of the endpoint default. |
| `data[].metrics.endAt` | string\|null | End of the reporting window. Must be paired with `startAt` so DataFast can build the date range. |
| `data[].metrics.lastUpdated` | string | Response generation timestamp. |

## Authentication

- **`df_` website API key:** The website is inferred from the key. You do not need a `websiteId` query parameter.
- **`dft_` account token:** Requires `analytics:read` permission and `?websiteId=` on every request. The token must be allowed to access that website.

Read [authentication and scopes](/docs/api/authentication) for token creation, permission lists, and scoped tokens.

### Errors

**400** — Invalid `funnelId` or partial date range.

**404** — Website or funnel not found (inactive funnels are excluded).

See [API errors](/docs/api#errors) for the standard error envelope, auth failures, validation errors, permission errors, and rate limits.

## Code examples

### Example request

```bash
curl -X GET "https://datafa.st/api/v1/analytics/funnels/{funnelId}" \
  -H "Authorization: Bearer df_xxx"
```

### Success response

```json
{
  "status": "success",
  "data": [{
    "funnel": {
      "id": "665f0b3c4d2e1a0012345678",
      "name": "Signup funnel",
      "slug": "signup-funnel",
      "steps": []
    },
    "data": [{
      "id": "landing",
      "label": "Landing",
      "value": 1000,
      "revenue": 2400,
      "stepIndex": 0,
      "stepType": "pageview",
      "conversionRate": 100,
      "dropoffFromPrevious": 0
    }],
    "metrics": {
      "totalVisitors": 1000,
      "completions": 214,
      "overallConversionRate": 21.4,
      "overallRevenuePerVisitor": 2.4,
      "timezone": "UTC",
      "startAt": null,
      "endAt": null,
      "lastUpdated": "2026-05-21T00:00:00.000Z"
    }
  }]
}
```