# Get the step funnel

`GET https://api.versionseven.ai/v1/campaigns/{campaign_id}/step-funnel`

The per-step funnel, annotated with the step at each position. Positions follow the sequence's own numbering; a connection check splits later steps into yes/no lanes. Replies are credited to the last message step before them. `waiting` is current state, not a window count.

`date_filter` takes a relative window such as `7d` or `30d`; `variation` restricts the funnel to `a` or `b`.

- Required scope: `campaigns:read`

## Request

**cURL**

```bash
curl "https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/step-funnel" \
  -H "Authorization: Bearer $VICTORIA_API_KEY"
```

**Node.js**

```javascript
const response = await fetch("https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/step-funnel", {
  headers: {
    Authorization: `Bearer ${process.env.VICTORIA_API_KEY}`,
  },
});

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

**Python**

```python
import os

import requests

response = requests.get(
    "https://api.versionseven.ai/v1/campaigns/550e8400-e29b-41d4-a716-446655440000/step-funnel",
    headers={
        "Authorization": f"Bearer {os.environ['VICTORIA_API_KEY']}",
    },
)
data = response.json()
```

## Headers

- `Authorization` (string, required): `Bearer` followed by a space and your API key, for example `Bearer vk_…`.

## Path parameters

- `campaign_id` (string · uuid, required): ID of the campaign.

## Query parameters

- `date_filter` (string or null, optional, at most 64 characters, example `"30d"`): Relative window ('7d', '30d', '90d') or an ISO-8601 timestamp to count from
- `variation` (string or null, optional, at most 32 characters, example `"a"`, one of `"a"`, `"b"`, `"unassigned"`, `"all"`): A/B arm to report on: 'a', 'b', 'unassigned' or 'all' (default)

## Response

### `200`

```json
{
  "campaign_id": "550e8400-e29b-41d4-a716-446655440000",
  "hidden_main_steps": 0,
  "note": "string",
  "steps": [
    {
      "channel": "email",
      "day": 1,
      "is_message_step": true,
      "lane": "main",
      "position": 1,
      "positive": 1,
      "positive_rate_pct": 1,
      "reached": 1,
      "replied": 1,
      "reply_rate_pct": 1,
      "step_id": null,
      "subject": "string",
      "type": "string",
      "waiting": 1
    }
  ],
  "success": true,
  "unattributed_outbound": 0,
  "unattributed_replies": 0,
  "variation": "all",
  "window_from": "string"
}
```

- `campaign_id` (string, required)
- `hidden_main_steps` (integer, optional, default `0`): Main-lane message steps sharing a position with a branch, and so not shown on their own row
- `note` (string or null, optional): How to read the numbers
- `steps` (array of objects, optional)
  - `channel` (string or null, optional, one of `"email"`, `"linkedin"`, `null`): 'email' or 'linkedin'
  - `day` (integer or null, optional): The day of the sequence the step falls on
  - `is_message_step` (boolean or null, optional): Whether the step sends something a prospect can reply to
  - `lane` (string or null, optional, one of `"main"`, `"yes"`, `"no"`): 'main', or 'yes' / 'no' for the branch of a connection check
  - `position` (integer or null, optional): The orchestrator's step number, counted from 1
  - `positive` (integer or null, optional): Positive replies credited to this step
  - `positive_rate_pct` (number or null, optional): positive / reached; null when nobody reached it
  - `reached` (integer or null, optional): Leads that reached this step in the window
  - `replied` (integer or null, optional): Replies credited to this step
  - `reply_rate_pct` (number or null, optional): replied / reached; null when nobody reached it
  - `step_id` (integer or number or string or null or null, optional): The sequence step's id at this position, when it could be matched. An integer on current sequences; older sequences may hold a fractional number or a string.
  - `subject` (string or null, optional): The email subject; only on email steps
  - `type` (string or null, optional): The step type at this position
  - `waiting` (integer or null, optional): Leads currently sitting at this step (current state; ignores the window)
- `success` (boolean, optional, default `true`)
- `unattributed_outbound` (integer, optional, default `0`): Sends that could not be matched to a step
- `unattributed_replies` (integer, optional, default `0`): Replies that could not be matched to a step
- `variation` (string, optional, default `"all"`): The A/B arm the report covers
- `window_from` (string or null, optional): Start of the window (ISO-8601); null = all time

## Errors

Errors share one JSON body: `success`, `error`, `message`, optional `details`, and `request_id`. For example:

```json
{
  "success": false,
  "error": "UNAUTHORIZED",
  "message": "Invalid or inactive API key",
  "request_id": "734d11a1-54d4-414c-9e8d-4e1ada977db4"
}
```

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `VALIDATION_ERROR` | The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`. |
| 401 | `UNAUTHORIZED` | The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated. |
| 401 | `API_KEY_EXPIRED` | The API key is past its expiry date. Create a new key in the Victoria AI app. |
| 403 | `INSUFFICIENT_SCOPE` | The API key doesn't have the scope this endpoint requires, such as `leads:write`. |
| 403 | `ORGANIZATION_DEACTIVATED` | The organization that owns this API key has been deactivated. |
| 404 | `CAMPAIGN_NOT_FOUND` | No campaign with this ID exists in your organization. |
| 404 | `NOT_FOUND` | No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`. |
| 429 | `RATE_LIMITED` | Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See [Rate limits](https://docs.versionseven.ai/guides/rate-limits). |
| 500 | `INTERNAL_ERROR` | Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support. |
| 503 | `UPSTREAM_TIMEOUT` | A service the API depends on timed out. The request is safe to retry. |
| 503 | `AUTH_UNAVAILABLE` | The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry. |

## Response headers

| Header | Description |
| --- | --- |
| `X-Request-ID` | Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead. |
| `RateLimit-Limit` | Requests allowed to this endpoint per minute. |
| `RateLimit-Remaining` | Requests you can still send to this endpoint right now. |
| `RateLimit-Reset` | Seconds until the endpoint's full limit is available again. |
| `Retry-After` | On a `429`: seconds to wait before retrying. |