Appearance
Funnels API
All paths are relative to https://your-site.com/api/v1. Send Authorization: Bearer <token> and Accept: application/json; see authentication and errors.
| Method | Path | What it does |
|---|---|---|
| GET | /sites/{site}/funnels/pages | Page addresses for page steps |
| POST | /sites/{site}/funnels/preview | Counts for unsaved steps |
| GET | /sites/{site}/funnels | The site's funnels (newest first) |
| POST | /sites/{site}/funnels | Creates a funnel (recordings:write) |
| GET | /sites/{site}/funnels/{funnel} | One funnel |
| PATCH | /sites/{site}/funnels/{funnel} | Renames a funnel or replaces its steps (recordings:write) |
| DELETE | /sites/{site}/funnels/{funnel} | Deletes a funnel (recordings:write) |
| GET | /sites/{site}/funnels/{funnel}/report | Sessions reaching each step, conversion and drop-off |
| GET | /sites/{site}/funnels/{funnel}/sessions | The latest 50 sessions that reached a step, or dropped out right after it |
GET /sites/{site}/funnels/pages
Page addresses for page steps
The site's most visited addresses of the last 30 days containing q (at most 20), with how many sessions viewed them.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
q | query | string |
Responses
- 200 — OK
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].url | string | ||
data[].sessions | integer |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/funnels/pages" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"POST /sites/{site}/funnels/preview
Counts for unsaved steps
Sessions reaching each step in the last 30 days, without saving anything (the builder's live numbers).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
steps | object[] | yes | At most 10 items. |
Responses
- 200 — One count per step.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.sessions | integer[] |
bash
curl -X POST "https://your-site.com/api/v1/sites/{site}/funnels/preview" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"steps":[{}]}'GET /sites/{site}/funnels
The site's funnels (newest first)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes |
Responses
- 200 — Funnels.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].id | integer | ||
data[].site_id | integer | ||
data[].name | string | ||
data[].steps | object[] | ||
data[].steps[].type | string | yes | One of: page, click, typed, tag. |
data[].steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
data[].steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
data[].steps[].key | string | Tag steps. | |
data[].steps[].label | string, nullable | Optional display name. | |
data[].created_at | string (date-time), nullable | ||
data[].updated_at | string (date-time), nullable |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/funnels" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"POST /sites/{site}/funnels
Creates a funnel (recordings:write)
403 when the account's plan allows no more funnels (plan feature funnels.count).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
name | string | At most 120 characters. | |
steps | object[] | At most 10 items. | |
steps[].type | string | yes | One of: page, click, typed, tag. |
steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
steps[].key | string | Tag steps. | |
steps[].label | string, nullable | Optional display name. |
Responses
- 201 — The funnel.
- 403 — Not allowed (not an administrator, or outside the token's abilities).
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.steps | object[] | ||
data.steps[].type | string | yes | One of: page, click, typed, tag. |
data.steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
data.steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
data.steps[].key | string | Tag steps. | |
data.steps[].label | string, nullable | Optional display name. | |
data.created_at | string (date-time), nullable | ||
data.updated_at | string (date-time), nullable |
bash
curl -X POST "https://your-site.com/api/v1/sites/{site}/funnels" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"text","steps":[{"type":"page"}]}'GET /sites/{site}/funnels/{funnel}
One funnel
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
funnel | path | integer | yes |
Responses
- 200 — The funnel.
- 404 — Missing, or another account's.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.steps | object[] | ||
data.steps[].type | string | yes | One of: page, click, typed, tag. |
data.steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
data.steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
data.steps[].key | string | Tag steps. | |
data.steps[].label | string, nullable | Optional display name. | |
data.created_at | string (date-time), nullable | ||
data.updated_at | string (date-time), nullable |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/funnels/{funnel}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"PATCH /sites/{site}/funnels/{funnel}
Renames a funnel or replaces its steps (recordings:write)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
funnel | path | integer | yes |
Request body
application/json, required
| Field | Type | Required | Description |
|---|---|---|---|
name | string | At most 120 characters. | |
steps | object[] | At most 10 items. | |
steps[].type | string | yes | One of: page, click, typed, tag. |
steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
steps[].key | string | Tag steps. | |
steps[].label | string, nullable | Optional display name. |
Responses
- 200 — The funnel.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.id | integer | ||
data.site_id | integer | ||
data.name | string | ||
data.steps | object[] | ||
data.steps[].type | string | yes | One of: page, click, typed, tag. |
data.steps[].op | string | Page and click steps. pattern: * matches anything. One of: is, contains, begins, pattern. | |
data.steps[].value | string, nullable | Page steps: the URL text. Click steps: the element text or selector. Typed steps: the field name. Tag steps: the value the tag must have (null = any). | |
data.steps[].key | string | Tag steps. | |
data.steps[].label | string, nullable | Optional display name. | |
data.created_at | string (date-time), nullable | ||
data.updated_at | string (date-time), nullable |
bash
curl -X PATCH "https://your-site.com/api/v1/sites/{site}/funnels/{funnel}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{"name":"text","steps":[{"type":"page"}]}'DELETE /sites/{site}/funnels/{funnel}
Deletes a funnel (recordings:write)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
funnel | path | integer | yes |
Responses
- 204 — Deleted.
- 404 — Missing, or another account's.
bash
curl -X DELETE "https://your-site.com/api/v1/sites/{site}/funnels/{funnel}" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"GET /sites/{site}/funnels/{funnel}/report
Sessions reaching each step, conversion and drop-off
A session reaches step 1 at its first matching event in the period (default: the last 30 days) and segment, and step k at its first matching event after reaching step k−1, in the same session. Per step: sessions, share (% of step 1), conversion (% of the step before), dropped (reached it but not the next step).
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
funnel | path | integer | yes | |
from | query | string (date) | ||
to | query | string (date) | ||
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — The report.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object | ||
data.funnel | object | ||
data.funnel.id | integer | ||
data.funnel.site_id | integer | ||
data.funnel.name | string | ||
data.funnel.steps | object[] | ||
data.funnel.created_at | string (date-time), nullable | ||
data.funnel.updated_at | string (date-time), nullable | ||
data.period | object | ||
data.period.from | string (date) | ||
data.period.to | string (date) | ||
data.conversion | number | % of step 1 that reached the last step. | |
data.steps | object[] | ||
data.steps[].step | object | A page the visitor viewed (type: page with op and value), an element they clicked (type: click with op and value: its text or CSS selector), a form field they typed in (type: typed with value: the field name contains; never what was typed) or a session tag (type: tag with key and optionally value). | |
data.steps[].sessions | integer | ||
data.steps[].share | number | ||
data.steps[].conversion | number | ||
data.steps[].dropped | integer |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/funnels/{funnel}/report" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"GET /sites/{site}/funnels/{funnel}/sessions
The latest 50 sessions that reached a step, or dropped out right after it
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
site | path | integer | yes | |
funnel | path | integer | yes | |
step | query | integer | yes | Minimum 1. |
outcome | query | string | One of: reached, dropped. Default "reached". | |
from | query | string (date) | ||
to | query | string (date) | ||
device | query | string | One of: desktop, mobile, tablet. | |
source | query | string | One of: direct, search, social, email, paid, referral. | |
visitor | query | string | One of: new, returning. |
Responses
- 200 — Session ids (replay at GET /sites/{site}/sessions/{session}) and when they reached the step.
- 404 — Missing, or another account's.
- 422 — Validation failed.
Response fields
| Field | Type | Required | Description |
|---|---|---|---|
data | object[] | ||
data[].session | string (uuid) | ||
data[].at_ms | integer |
bash
curl -X GET "https://your-site.com/api/v1/sites/{site}/funnels/{funnel}/sessions" \
-H "Authorization: Bearer $REPLORA_TOKEN" \
-H "Accept: application/json"