Workflow funnel

GET/v1/workflows/{id}/stats

Secret key — sk_… or sk_test_… · Base URL https://api.volanea.com

The enrolment funnel for one workflow: entered → delivered → opened → clicked → converted, each with the drop from the stage before it.

The funnel counts distinct contacts; totals counts messages. A three-email drip sends three messages to one person, so a funnel counted in messages would report more delivered than entered and stop being a funnel at all. The two numbers differ for that reason, not by mistake.

Conversion is whatever you say it is. Volanea stores no conversion of its own — what counts as one is a property of your product. Name any event you already send to POST /v1/events as conversionEvent and it becomes the last stage. Only conversions that happened at or after the contact entered are counted; attributing a purchase that predates the enrolment would flatter every funnel aimed at people who already buy. Omit the parameter and the stage is absent rather than zero, because "no goal set" and "nobody converted" are different answers.

Engagement is aggregated from the send log on read rather than kept as counters on the workflow, so these numbers are real for workflows that ran long before this endpoint existed.

Path parameters

idstringrequired
Workflow id.

Query parameters

daysinteger
Window length in days (1–365, default 30).
conversionEventstring
One of your own event names, e.g. `order.placed`. Adds the `converted` stage.

Response

The funnel.

workflowIdstring
namestring
statusstring
windowobject
- daysinteger
- fromdate-time
- todate-time
testModeboolean
funnelobject[]
Stages in order, in distinct contacts.
- stageenum
  entereddeliveredopenedclickedconverted
- countinteger
- rateOfEnterednumber
  Percentage of the contacts that entered.
- dropFromPreviousinteger | null
  Contacts lost since the previous stage; null on the first.
totalsobject
Messages, not people.
- messagesinteger
- unsubscribedinteger
- byStatusobject
executionsobject
Enrolment counts by execution status.
conversionEventstring
Echoed back when one was named.

Errors

Every failure returns the standard envelope — branch on `code`, never on the wording of `error`.

401Missing or invalid API key.
404Not found.
422Request validation failed (code `validation_error`, 422).

Request

curl https://api.volanea.com/v1/workflows/id_123/stats?days=30&conversionEvent=value \
  -H "Authorization: Bearer sk_..."

Response

200 · application/json

{
  "success": true,
  "data": {
    "workflowId": "wf_7d31",
    "name": "Welcome",
    "status": "<status>",
    "window": {
      "days": 1,
      "from": "hello@yourdomain.com",
      "to": "ada@example.com"
    },
    "testMode": true,
    "funnel": [
      {
        "stage": "entered",
        "count": 1,
        "rateOfEntered": 1,
        "dropFromPrevious": 1
      }
    ],
    "totals": {
      "messages": 1,
      "unsubscribed": 1,
      "byStatus": {}
    },
    "executions": {},
    "conversionEvent": "<conversionEvent>"
  }
}

92 endpoints · OpenAPI document