Skip to main content
Measure how often AI recommends or names brands across topics, markets, engines, or weeks — use for competitor benchmarks, share-of-voice reports, and proving whether content or PR moved the needle. Pass subject (brd_ id or domain) or group by brand (by brand omits citations/comparisons). Covers ChatGPT and Google AI Mode unless filter.engine, filter.surfaceClass, or by says otherwise. Every cell includes answers, questions, and 95% range; compare: “prior” adds matched-question change and significance; by: [“question_group”] clusters questions by meaning. For head-to-head wins by axis, use comparisons/comparisons_won/comparisons_lost with by: [“versus_brand”, “axis”]. Older than 90d public answers: $0.001 each once (history). Free.

Who may call it, and what it costs

Price. Free over the last 90 days. A public answer older than 90 days costs $0.001 the first time the workspace counts or lists it, and is the workspace’s after, shown in meta.costCredits. A call whose window reaches further back counts one even sample of its answers, the deepest whose past answers, owned or not, are worth at most 25% of the month’s budget in effect, at most $5, bought when called with no quote (history: "auto"); history: "all" counts every answer within the month’s budget, and history: "free" reads the last 90 days only and says what each sample would cost. Every reply says what the call cost in meta.costCredits. The prices are on Spending, tracking and stopping.

Arguments

list of one of answers, questions, answers_naming, share_named, share_recommended, share_first, share_spread, avg_position, tone_mix, treatment_mix, mentions_with_objection, citations, citations_first, avg_citation_rank, pages_cited, sites_cited, questions_citing, weeks_cited, share_citing, comparisons, comparisons_won, comparisons_lost, search_reach, memory_gap, concentration, listing_share, page_type_mix, hedge_mix, own_site_citations, causal_funnel, descriptor_words
required, except with by: [“question_group”] (answers per group) up to 12
string
brd_ id the shares are about; or group by brand. With no filter it reads the brand’s own markets (up to three) pooled, named in context.marketsRead: pass filter.market for one market’s number
list of string
up to 3 of brand, topic, market, question, engine, surface_class, place, country, day, week, month, site, page, page_type, axis, versus_brand, or facet:<key>; or [“question_group”] alone: the questions grouped by meaning up to 3
object
which answers count; window is a separate argument, not part of filter
list of string
brd_ ids; with brandRule, which answers count up to 20
one of named, recommended, first, not_named, not_recommended, warned
default named; not_recommended keeps judged answers recommending none of the filter brands; warned filters to answers flagged with facet mention.advised_against
one of any, all
with several brands; default any
list of string
up to 50
list of string
Industry or category markets. For countries use country, and for cities use place. up to 50
list of string
up to 100
list of string
surface ids (resolve_ids with kinds: [“surface”] lists them); without engine or surfaceClass, the counted engines up to 10
list of one of counted, wider, memory, search, imported
classes of engines to cover; default counted up to 5
"all" or list of string
plc_ ids (resolve_ids finds them): the place a question is about, with the places under each (a region holds its cities). “all”: every place, in place of a local subject’s area. A country code here reads as filter.country for one release
list of string
ISO country codes the question was asked from; an answer asked with no place set counts as US up to 20
list of string
domains or site: ids of cited sites up to 50
list of string
pg_ ids of cited pages up to 50
string
Full-text search over answer text: keywords, “exact phrases”, AND/OR/NOT, NEAR/n, prefix*. A call reads at most the first 100,000 matches (20,000 in search_answers) before the brand filter and the rest apply: a brand filter does not narrow it, so a common word over a long window can miss a brand’s answers; narrow by window, topic, market or engine
object
a facet with “filter” in its usableIn list
one of tracked, public, own, all, index
default all: public plus this workspace’s own; own: only the answers this workspace bought; tracked: its own answers and those about the questions, topics and brands it watches with the track tool (not the brands it added in the app); public: public answers only; index: the answers parse.gl’s public pages count, which a logged-out call always reads
object
default the last 28 days; “last” or from/to
one of 7d, 28d, 90d, 365d, all
date
inclusive
date
inclusive
one of auto, all, free
answers past 90 days, $0.001 each once: auto (default) a sample worth up to a quarter of the month’s budget, at most $5; all, every answer within the budget; free, none, with each sample’s cost
one of company, product
how brands count: company (default; a company and its products are one brand) or product (each brand on its own, so a product’s numbers leave out its siblings)
one of prior, none
prior: the window of equal length before, with significance; none: no comparison. Write the value bare, compare: prior, with no quotes inside the string
one of matched, all
changes on matched questions (default) or every question
string
a measure or a by dimension; “<name> asc” or “<name> desc”
integer
default 25; the token cap wins min 1, max 200
string
one of compact, full
compact (≈6k tokens, default) or full (≤20k)
list of string
columns to keep in each row up to 40
boolean
list of string
with by brand: only these brands’ rows, against each other in the same answers (in place of the most named) up to 25
boolean
with by brand: rank every brand named, not the 50 named most (signed in)
integer
with two dimensions in by: the first N rows within each value of the first min 1, max 50
boolean or "change"
false: leave out the one-sentence note (data.note). change (with subject, a share and compare prior): why each share moved, split into the same questions and the question mix, with engine model changes
number
question_group only: how alike a question must be to its group’s first to join it; default 0.75 min 0.6, max 0.95
boolean
question_group only: default true, each group lists up to 20 of its questions; false lists none, so a page holds many more groups
Every argument the tool takes, as GET /v1/tools serves it, every shared object written out; https://agent.parse.gl/openapi.json serves the same schema with the filter and the window named once under components and pointed to by $ref. MCP tools/list leaves out the arguments few calls send, and says the filter and the window once, under search_answers; resolve_ids {"kinds": ["argument"]} lists what it left out, and a call with any of them runs:

Example call

How often AI names and recommends a brand in a market, and whether that changed. Over REST:
Over MCP, the assistant calls the tool by name with the same arguments:
More calls:
  • Rank the brands of a market against each other: {"measures":["share_named","share_recommended"],"by":["brand"],"filter":{"market":["mkt_6956b477-23eb-43da-99ad-c3e612482b08"]},"window":{"last":"28d"}}
  • Rank a market’s brands over the answers its parse.gl page counts, each with its place (rank, ties shared): {"measures":["share_named"],"by":["brand"],"filter":{"market":["mkt_6956b477-23eb-43da-99ad-c3e612482b08"],"scope":"index"},"level":"product"}
  • How AI qualifies a brand, how often it cites the brand’s own site, and the words it uses for the brand: {"measures":["hedge_mix","own_site_citations","descriptor_words"],"subject":"brd_21e2e46d-5498-46bc-bd54-791c1acd74e7","filter":{"scope":"index"},"level":"product","window":{"last":"90d"}}
  • Group a market’s questions by what they ask, with how often the brand is named in each group: {"measures":["answers"],"by":["question_group"],"filter":{"market":["mkt_6956b477-23eb-43da-99ad-c3e612482b08"]},"subject":"brd_21e2e46d-5498-46bc-bd54-791c1acd74e7","members":false,"limit":10}
The reply has data, context, next, page and meta; follow next for the calls that come after. A refused call returns { code, message, fix }: see the error table.