Form Report

Shows you how your forms convert, and the submissions and revenue they capture.

Use it when a signup or demo form is losing people and you need to know where — or when you want to read back what people actually typed into it.

The question it answers: which forms turn visitors into leads, and what did those leads go on to be worth?

Two ways to call it

What you get

Where the numbers come from. Product events count exact unique people over the report's range, not estimates or samples, and they are aggregate. The submissions list is the one exception: it is per-person, not aggregate. The Precision notes at the end of this page give the exact warehouse wording.

Reach revenue vs causal revenue

Both appear on every row, and reach is always the larger number:

• Reach revenue — money from everyone who touched the form, whenever they paid. It sizes the audience; it is not a claim that the form caused the sale.
• Causal revenue — money the form can plausibly claim: people who bought in the same session, or who were demonstrably influenced by it.

Reach overlaps across forms. FullVision counts a person who submitted three forms under all three, so adding reach numbers across forms invents revenue that does not exist. Compare forms to each other; never total them.

Group form — omit form_id

One row per form — starts, submits and the completion rate, joined to reach and causal revenue — ranked by revenue. A form that has revenue but no traffic in range still appears, so the list is complete.

Single form — supply form_id

Parameters

The series array — granularity

granularity is purely additive: rows is unchanged, and omitting it returns exactly the previous response. Each point carries form_starts, form_submits and submit_rate_pct.

The series is funnel metrics only. Reach revenue overlaps across forms, so bucketing it over time would read as additive when it is not.

FullVision labels each bucket with its start date (Monday for weekly) and returns them oldest first. The trailing bucket may be partial — compare it against range.to. Do not add the buckets up to get the range totals — rate metrics are recomputed per bucket. Use rows for totals.

FullVision analyses popup/modal capture separately and does not expose it in v1.

Ranking, totals and comparison

Three group-form parameters, each independently opt-in. Omit all three and the response is exactly the one you got before they existed — no totals, no totals_meta, no prior.

Re-ranking the list — order_by

order_by is a closed enum per report — the legal columns are listed in the order_by dropdown of the API panel above. Omit it and you keep the default revenue ranking, unchanged. order_dir is asc or desc, defaults to desc, and does nothing on its own.

• The re-rank applies to the complete form list, before limit — a form the revenue ranking buried below the limit surfaces, rather than the same top-20 reshuffled.
• Nulls sort last in both directions. A form whose page never appears in the traffic view has no page_views; that is unknown, not zero, and floating it to the top of an ascending sort would bury the forms you asked to see.
• Ties always break on form_id ascending, so the order is total and repeated calls return the forms in the same order.

Whole-set totals — totals

totals=true adds a totals object covering the complete filtered set before limit — every form, not just the returned ones — plus a totals_meta sidecar. Anything other than true/false is a 400; nothing is coerced.

Rates are recomputed from their bases over the whole set, never summed or averaged across rows: submit_rate_pct is whole-set submits over whole-set starts, not the average of the per-form rates.

totals_meta.upper_bound names the columns whose total overcounts, because per-row values overlap between rows. Render these as approximations, not counts — this is the same overlap the reach warning above describes:

The causal revenue columns are not marked: they are the MECE per-charge complement, so they sum exactly.

totals_meta.omitted names the columns deliberately left out, so their absence reads as a decision rather than a bug:

A fields trim trims totals with it: neither totals nor prior ever describes a column the response itself does not carry.

Comparing against a prior window — compare_to

compare_to attaches a prior object to each row, measured over a second window:

• prior: null means the form did not exist in that window. That is a different claim from a prior object of zeros, which means present and measured zero; conflating them reports a brand-new form as flat.
• Prior-only rows are not introduced. A form that collected then and is retired now does not appear — the list is still the current window's.
• The prior window differs only in its dates: same workspace, same page_url_scope, same filters, same fields.
• Independent of totals. A nested totals.prior appears only when both are set.
• compare_to roughly doubles the cold-path work — every query this report issues runs a second time over the prior window. Only Page Report memoizes its ranked set; this one does not.

Trimming the response — fields

fields is a comma-separated list of response blocks. Omit it and you get every block — it only ever narrows a response, never widens one, so every existing call keeps its exact shape.

The two forms do not accept the same names — submissions exists on the single form only:

?fields=funnel                       → group rows keep only the funnel columns
?form_id=newsletter&fields=submissions → the single form keeps only the captured list
?fields=submissions                  → 400 — `submissions` is single-form only

Rules that bite:

• FullVision resolves the legal set AFTER form selection, not per endpoint. Supplying form_id picks the single form and its block list; omitting it picks the group form and its own. submissions therefore 400s without form_id, naming the blocks legal on the group form.
• Empty, duplicated, unknown, and * are all 400s — fields=, fields=funnel,funnel, fields=nope, fields=*. A stray comma is a typo, not a request for everything. The error message lists the legal blocks inline.
• Trimming does not guarantee a query saved per block. Sources are shared: on the single form funnel and pages are two folds of the same form-performance read. The contract is correct trimming — you get exactly the blocks you asked for and nothing else — never one fewer round trip per block dropped.
• fields selects columns, never which rows exist. ?fields=events returns the same forms the untrimmed call does, with only the events column on each. The Precision notes say which queries decide the list.
• Row identity is never droppable. form_id, host_scope and range survive every trim.
• granularity is independent. The series array is not a block: ?fields=revenue&granularity=weekly still returns one.
• fields never lowers the scopes the endpoint requires. ?fields=funnel still needs customer:read alongside attribution:read and web:read, and submissions is still personal data.

Landing-page traffic — page_paths and page_views

Each group row carries the pages the form appeared on in range, and their summed traffic. Use them to tell "nobody sees this form" apart from "everybody abandons it".

• page_paths — the distinct pages where visitors saw the form (raw, host-qualified).
• page_views — summed page_views of those pages, or null when none of them appear in web-pages for the range.

null is not 0. null means no traffic data for those pages (render "—"); 0 means the pages exist and genuinely had no views. Forms that only ever appear via form-revenue — with no form-performance row in range — have an empty page_paths and therefore null views.

The endpoint returns paths raw. Dashboards that collapse per-user id segments (/dashboard/60843/home → /dashboard/:id/home) should keep doing that client-side; the report deliberately does not, because a workspace can legitimately want the real paths.

Segmenting the series — series_by

Supply series_by alongside granularity (group form only) to split the series by one dimension instead of returning scope-level totals. series then holds one point per (bucket × segment), each carrying key — the segment value — so the response can feed a stacked or multi-line chart directly.

Accepted here: form_id.

granularity=weekly                 → [{ date, <metrics> }, …]
granularity=weekly&series_by=form_id  → [{ date, key, <metrics> }, …]

Notes that bite:

• A source view that has no breakdown for the requested dimension is dropped from the segmented series, not smeared across every segment — copying a scope-level total onto each segment would read as per-segment data and be wrong. So a segmented series can carry fewer metric keys than the flat one.
• FullVision skips rows whose dimension value is blank: an unnamed series cannot be labelled or filtered by the caller.
• An unrecognised series_by returns an empty series (not an error, and not a silent fallback to the flat series).
• Segment values may contain spaces (search queries, campaign names) — key is the full value.
• rows is unaffected. Do not sum segmented buckets to get range totals; use rows.