Skip to main content

List Funnel Revisions

Every save of an AI/HTML funnel's draft (an AI build, an edit in the editor, an import, a restore) is kept as a numbered revision, and none is deleted with age. This route lists them, newest first. After an A/B test is ended, the history starts where the winning version was created. Download any of them with Get Funnel HTML.

GET /v1/funnels/{funnelId}/revisions

:::note Rolling out Revision history is being enabled workspace by workspace. Until it is enabled for yours, this route answers 404. :::

Authentication​

A signed-in user only: send the OAuth access token the MCP server and the CLI use, as Authorization: Bearer <access token> (see Bearer tokens). Funnels are not available to API keys: a request with x-perspective-api-key is refused with 403.

The user must be able to open the funnel in the app.

Parameters​

NameInTypeRequiredDescription
funnelIdpathstringYesID of an AI/HTML funnel.
versionqueryoriginal | variantNoOn a funnel with an A/B test, whose history to list (default original). The two versions have their own revisions.
limitqueryinteger, 1–100NoRevisions per page (default 20).
offsetqueryinteger, ≥ 0NoRevisions to skip (default 0).

Example request​

curl "https://api.perspective.co/v1/funnels/$FUNNEL_ID/revisions?limit=20" \
-H "Authorization: Bearer $ACCESS_TOKEN"

Response​

Returns { data: Revision[], meta: { limit, offset } }. A page shorter than limit is the last one.

FieldTypeRequiredDescription
revisionintegerYesThe revision's number, counted per version. Pass it to Get Funnel HTML as revision.
sourcestringYesWhat wrote it: manual (the editor), code-editor, ai-funnel (an AI build), mcp, import or restore.
createdAtstringYesWhen it was saved (ISO 8601).
authorobjectNo{ id, name? } of the user who saved it. Absent when no user did, or the user is gone.
publishedAtstringNoWhen this revision first went live. Absent means unknown, not "never published": publishes before revisions were recorded carry no date.
isLivetrueNoPresent on the revision marked live: the one last published.
restoredFromintegerNoOn a restore: the revision it brought back.
groupstringNoRevisions written by one AI build share it. Collapse them into one entry if you show a history.

Example response​

{
"data": [
{ "revision": 42, "source": "manual", "createdAt": "2026-11-19T10:12:03.000Z", "author": { "id": "64b7…", "name": "Ada Lovelace" } },
{ "revision": 41, "source": "ai-funnel", "createdAt": "2026-11-18T16:40:11.000Z", "group": "build-7f3a", "isLive": true, "publishedAt": "2026-11-18T16:45:00.000Z" }
],
"meta": { "limit": 20, "offset": 0 }
}

Errors​

Errors carry a code beside error and status. See Errors.

StatuscodeMeaning
400funnelId or a query parameter is invalid.
401Missing, invalid or expired access token.
403An API key was sent: funnels need a signed-in user.
404FUNNEL_NOT_FOUNDNo AI/HTML funnel with this ID that you can open.
404EXPERIMENT_ARM_MISSINGversion=variant on a funnel without an A/B test.