Keyword Report

Ranks the search keywords you show up for by the revenue they earned, and flags the ones a rewrite would move.

Use it when you are picking what to publish or refresh next, or when you need to answer "which searches make us money?" rather than "which searches make us traffic?".

The question it answers: which queries bring people who pay — and which near-miss queries are one rewrite away from doing so?

Two ways to call it

What you get

Where the numbers come from. Search metrics are our synced Google Search Console (GSC) data — not live — except the opt-in live breakdown, which calls Google at request time. Product events count the first-touch acquisition population: people acquired via the keyword who later fired the event. Those counts are exact unique people over the report's range, not estimates or samples, and they are aggregate only: the report returns no personally identifiable information (PII). The Precision notes at the end of this page give the exact warehouse wording.

Parameters

The series array — granularity

granularity is purely additive: rows is unchanged, and omitting it returns exactly the previous response. Each point carries new_customers, existing_customers, new_customer_revenue, existing_customer_revenue, attributed_revenue, gsc_clicks, gsc_impressions, gsc_ctr_pct and gsc_avg_position.

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.

Use Ad Report for the paid-search counterpart.

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, and the same cursor.

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 attributed-revenue ranking over the merged organic + paid-only set, unchanged. order_dir is asc or desc, defaults to desc, and does nothing on its own.

• The re-rank applies to the complete row set, before limit — a keyword the default ranking buried below the limit surfaces, rather than the same top-20 reshuffled.
• The GSC and paid_* columns are sortable here, unlike on Page Report: they ride the query that produces the complete set rather than being filled in afterwards. A paid-only row reads its paid columns from the merged set, so sorting by paid_spend_cents ranks organic and paid-only keywords on one axis.
• Nulls sort last in both directions. A paid-only keyword has no gsc_avg_position; that is unknown, not worst.
• Ties always break on the query ascending, so the order is total and a cursor walk visits every row exactly once.

Cursors under a non-default ordering

next_cursor is still echoed back into starting_after verbatim — never construct or parse the value. Under the default ranking it is the bare row identity it has always been. Under any order_by it becomes an opaque token that also carries the ordering, so replaying a cursor under a different order_by / order_dir is a 400 rather than a silent relocation into another ordering. Repeat the original ordering on every page of a walk, or restart from page one.

Whole-set totals — totals

totals=true adds a totals object covering the complete filtered set before limit — the number you would otherwise get by walking the cursor to the end — 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: gsc_ctr is whole-set clicks over whole-set impressions, still as a fraction (a 3.2% CTR reads 0.032).

totals_meta.upper_bound is empty on this report — every summed column partitions cleanly across keywords.

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 keyword 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 keyword as flat.
• Prior-only rows are not introduced. A keyword that ranked then and does not now will 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.

The paid half — paid_* and source

Rows merge the organic GSC keyword with its paid counterpart from ads-performance at level=keyword, which is Google-only — the other ad platforms have no keyword level at all. Use these columns when you want to see whether you are paying for a click you already earn organically.

Matching is case-insensitive: the GSC query sales navigator export merges with the ad keyword Sales Navigator Export.

Things to know:

• Both money columns are cents. spend is major units on the underlying ads view and FullVision converts it here, so every money field on a report row shares one unit.
• A workspace with no ads connection gets zeros, not an error. Paid data is an enrichment; a failing ads view never takes the organic report down.
• Paid-only keywords are their own rows (source: "paid", zero GSC columns) and compete for the same limit slots as organic ones, ranked on the shared cents axis. They are addressable in the single form too.
• Mixed currencies. Currency is a grouping dimension on the ads view; this roll-up keys on the keyword alone, so a workspace running one keyword across several account currencies gets a mixed-currency sum.

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.

?fields=attribution        → rows keep only the revenue columns
?fields=gsc                → GSC metrics + the opportunity flags
?query=evaboot&fields=gsc  → the single form's performance.gsc_* plus its trend

Rules that bite:

• attribution and gsc share one query. keyword-performance fills both, so dropping just one saves no round trip — it only narrows the payload. Dropping both skips it. The contract is correct trimming, never one fewer query per block dropped.
• paid genuinely changes which keywords appear. Paid-only keywords exist in the response solely because of ads-performance, so a response that includes paid can list keywords an attribution-only one does not. Every other block leaves the row set alone — the Precision notes say which query decides it.
• passthrough is not a block. gsc_breakdown controls it alone. ?gsc_breakdown=device&fields=attribution still performs the live Search Console call, still fills passthrough, and still 502s if that upstream fails — an explicit opt-in outranks an omission.
• Empty, duplicated, unknown, and * are all 400s — fields=, fields=gsc,gsc, fields=nope, fields=*. The error names the legal blocks.
• Row identity is never droppable. query, host_scope and range survive every trim.
• granularity is independent. The series array is not a block.
• fields never lowers the scopes the endpoint requires. ?fields=paid still needs search:read alongside attribution:read and web:read.

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: query.

granularity=weekly                 → [{ date, <metrics> }, …]
granularity=weekly&series_by=query  → [{ 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.