Read your funnels from your own systems

A funnels.read key, and the four calls that return your funnels, their reports, their weekly trends and this month's usage.

Your funnels can also be read with an API key: the funnels you built, each one's report and its step trends, and how much of this month's allowance you have used. Use it to put your conversion on your own dashboard, in a weekly email or in your data warehouse.

The answers are the same ones the page shows, calculated by the same code, so the numbers match.

Create a key that can read funnels

Open Settings → Integrations and click Create key under API keys.
Give it a name, such as Dashboard.
Under What it can do, tick Read funnels (funnels.read). Nothing is ticked to start with: tick only what the key needs.
Click Create key and copy it. It is shown only once.

Any member of the workspace can create one. A key can't gain a scope later, so a key that only sends steps (funnels.write) can't read: create a separate key for reading, or one with both ticked.

Every call sends the key as a bearer token. The key decides the workspace, so no workspace id goes in the address.

Call the API from a server or a scheduled job, never from code that runs in a browser. A key in a web page is a key anyone can copy, and the API doesn't answer calls made from other websites anyway: a dashboard reads through its own backend.

List your funnels

curl https://api.outcomify.com/api/funnels \
  -H "Authorization: Bearer ock_…"

[
  {
    "id": "3f1c…",
    "name": "Activation",
    "steps": [
      { "key": "signed_up", "name": null, "events": ["signed_up"] },
      { "key": "created_project", "name": "Created a project", "events": ["created_project", "imported_project"] },
      { "key": "invited_teammate", "name": null, "events": ["invited_teammate"] }
    ],
    "conversionWindowDays": 30,
    "createdAt": "2026-10-01T09:12:00+00:00",
    "updatedAt": "2026-10-12T14:03:00+00:00"
  }
]

Use a funnel's id in the calls below.

Read a funnel's report

curl "https://api.outcomify.com/api/funnels/3f1c…/report?days=30" \
  -H "Authorization: Bearer ock_…"

days is the period, 1 to 180, and is 30 when left out. The report is the one described in Read the report: people at each step, the share from the start and from the step before, the typical time between steps, and the same period before for comparison.

{
  "funnelId": "3f1c…",
  "name": "Activation",
  "from": "2026-09-18T10:00:00+00:00",
  "to": "2026-10-18T10:00:00+00:00",
  "conversionWindowDays": 30,
  "steps": [
    { "event": "signed_up", "people": 1200, "fromStart": 1, "fromPrevious": 1, "medianSecondsFromPrevious": null, "previousPeople": 1100, "name": null, "paths": null },
    { "event": "created_project", "name": "Created a project", "people": 540, "fromStart": 0.45, "fromPrevious": 0.45, "medianSecondsFromPrevious": 5400, "previousPeople": 470,
      "paths": [{ "event": "created_project", "people": 400, "share": 0.74, "nextPeople": 150, "toNext": 0.375 }, "…"] },
    { "event": "invited_teammate", "people": 190, "fromStart": 0.158, "fromPrevious": 0.352, "medianSecondsFromPrevious": 172800, "previousPeople": 160, "name": null, "paths": null }
  ],
  "conversion": 0.158,
  "previousConversion": 0.145,
  "changeMargin": 0.02,
  "changeSignificant": false
}

Shares are between 0 and 1. paths is filled in only for a step with more than one event, and is null otherwise. The examples here are trimmed: a field you don't see in them may still be in the answer.

Read a funnel's step trends

curl "https://api.outcomify.com/api/funnels/3f1c…/trends?weeks=12" \
  -H "Authorization: Bearer ock_…"

weeks is how many weekly cohorts, 2 to 52, and is 12 when left out. This is the data behind Step trends: each step's conversion from the step before, week by week, its recent weeks against its earlier ones, and the tree work linked to each step.

{
  "funnelId": "3f1c…",
  "name": "Activation",
  "steps": ["…as in the list…"],
  "conversionWindowDays": 30,
  "weeks": [
    { "start": "2026-07-27T00:00:00+00:00", "complete": true, "people": [280, 120, 41] },
    "…",
    { "start": "2026-10-12T00:00:00+00:00", "complete": false, "people": [190, 70, 12] }
  ],
  "transitions": [
    { "step": 1, "from": "signed_up", "to": "created_project", "weekly": [0.43, "…", 0.37],
      "earlier": 0.42, "recent": 0.47, "change": 0.05, "margin": 0.03, "significant": true,
      "earlierPeople": 1500, "recentPeople": 1450, "ship": null }
  ],
  "markers": [],
  "links": [],
  "mostMoved": 1
}

A week is complete once its conversion window has passed; until then its later steps can still grow. markers are linked solutions completed in the period, and links the tree nodes tied to each step.

When a solution linked to a step shipped in these weeks, that step's ship compares the weeks before it with the weeks since: before, after, change, margin and significant, with nodeId, displayId, nodeTitle and at for the solution. after is null while no week since has finished (too early to tell), and weeksAfter says how many have. Step trends explains how the weeks are split. mostMoved is the step that moved most, judged by ship where there is one: the step the page marks Moved most, or null when none really moved.

Read this month's usage

curl https://api.outcomify.com/api/funnels/usage \
  -H "Authorization: Bearer ock_…"

{ "month": "2026-10-01", "recorded": 48213, "limit": 250000 }

recorded is how many step records this month has used, and limit is your plan's monthly allowance. See Busy apps, 429s and backfills for what happens at the limit.

Rate limits

Each workspace can make 60 read calls a minute, however many keys it has. Past that, the answer is 429 Too Many Requests with a Retry-After header in seconds: wait that long and try again. Reads have their own limit, so they never use up the calls your backend needs to send steps.

A report or a trend changes slowly. Reading each funnel every few minutes, or once a night for a warehouse, is plenty.

Status	Means
`400`	`days` or `weeks` isn't a whole number in its range. The answer says the range. Leave one out, or empty, to get its default.
`401`	The key is missing, wrong or revoked.
`403`	The key doesn't have the `funnels.read` scope. Create one that does.
`404`	No funnel with that id in the key's workspace.
`429`	Too many calls this minute. Wait the seconds in `Retry-After`.

Changes to the API

The API has no version number in its address. We may add fields to these answers, so ignore any you don't recognise. We won't remove or rename a field without announcing it in What's new first.