Why Claude says your Meta ads metric doesn't exist
The connector translates your words into canonical field names before it fetches anything. There is a tool that shows you the dictionary, and the words it does not hold are the ones you use every day.
The connector does not look your metrics up by the names you use. It resolves them against a
field catalogue, and that catalogue is narrower than your vocabulary. Asked on 2026-09-07,
roas, cpa, cpl, add_to_cart,
thruplay and quality_ranking all returned as unknown fields. The real
names are purchase_roas, cost_per_omni_purchase,
cost_per_lead and omni_add_to_cart. spend works, because it
is a listed alias. budget does not.
You ask for cost per acquisition broken out by ad. What comes back is a number, confidently labelled, and it is cost per result — a different quantity that happens to be close enough that you do not query it. Or you ask for ThruPlay and get watch time. Or you ask for quality ranking and get a paragraph about relevance instead of a column.
None of that is the model being vague. Behind every one of those answers is a lookup that either resolved to a canonical field name or quietly did not, and the connector ships a tool whose only job is to show you which. It is worth ten minutes precisely because it converts an argument about whether the assistant is trustworthy into a list of strings you can check.
The catalogue is the vocabulary
The field-context tool describes itself as returning “rich metadata for ads fields (canonical name, display name, type, description, filterability, sortability, enum values, aliases, metric flag, supported levels)”. Four of its five stated uses are about translation before a query rather than reporting: confirm a field exists, resolve an alias, get the enum values before building a filter, and see which levels support the field. The fifth is browsing — omit the argument entirely and its schema says it returns every field in the catalogue.
The output has two halves. Names that resolve come back as full metadata entries. Names that do
not come back in a separate unknown_fields array, sitting next to the ones that worked.
That shape matters more than it sounds: a request mixing good and bad names does not fail. It
half-succeeds, and the half that failed is a line in a list an assistant may or may not mention
before it starts writing prose around the fields that survived.
The schema tells you to use it to “resolve an alias (e.g. spend ->
amount_spent, actions:lead -> lead)”. The first half
is true: spend is listed as an alias of amount_spent. The second is not.
Asked for actions:lead on 2026-09-07, the catalogue returned it in
unknown_fields; lead's only alias is leads. The
actions: prefix convention is genuinely there — omni_purchase lists
actions:omni_purchase, link_click lists actions:link_click
— it just does not cover the example the documentation picked.
Knowing the canonical name for the metric you actually manage on is the difference between a report and a plausible-looking substitute. The Claude Ads Operator course builds its reporting prompts on canonical names for exactly this reason.
| What you type | What the catalogue calls it | Does your word resolve? |
|---|---|---|
spend | amount_spent | Yes — listed alias |
roas | purchase_roas | No |
cpa | cost_per_omni_purchase | No — but cost_per_purchase does |
cpl | cost_per_lead | No |
add_to_cart | omni_add_to_cart | No — but adds_to_cart does |
budget | daily_budget | No |
thruplay, quality_ranking | — | No, and nothing obvious replaces them |
Two fields for “is it running”, and the case matters
The clearest thing the catalogue gives you is the distinction between the status an advertiser
set and the status Meta is acting on. status describes itself as “the configured
(advertiser-set) status of the entity” and then points elsewhere: “For the actual
delivery state (which may differ due to parent state, review, or billing) use the
delivery field.”
Follow that pointer and you land on a field whose values are lowercase — draft,
pending, active, inactive, error,
completed, off. Meanwhile effective_status also exists, also
covers delivery state, and its values are uppercase: ACTIVE, WITH_ISSUES,
DISAPPROVED, PENDING_REVIEW, PENDING_BILLING_INFO. Two fields
answer roughly the same question in two different casings, and a filter written against the wrong
one is a filter that matches nothing while looking entirely reasonable. This is the class of thing
that produces an empty result you then read as “no ads are broken”.
What to check, in order
-
Look the name up before you ask for the number START HERE
One lookup, listing the handful of metric names in your weekly review, tells you which of your words the connector speaks. It takes a few seconds and it is the only step here that changes every query you write afterwards. The trade: the catalogue is a dictionary, not an inventory. A field resolving tells you the name is legal; it says nothing about whether your account has data behind it.
-
Read
levelsbefore asking for a breakdownEvery entry lists which of campaign, ad set, ad and account support it, and the gaps are not where you would guess.
conversionsis campaign-only, and it comes backfilterable: falsewith an empty operator list — so “show me conversions per ad, highest first” is not a hard question, it is an impossible one.cost_per_resultis missing at account level.objectiveexists at campaign and ad, but not ad set. -
Treat filterable and sortable as separate facts
They are separate flags and they genuinely disagree.
daily_budgetis filterable but not sortable, so you can ask for everything above a threshold and not for a ranking.bid_strategyis neither, and although its type isENUMitsenum_valuescame back null — the tool's headline use case, getting valid values before writing a filter, produces nothing for that field.
A name the catalogue does not hold is a question the connector answers with something adjacent.
- Expecting an unknown name to fail loudly. It does not. It lands in
unknown_fieldsbeside the names that worked, and the answer is built from the remainder. This is one of the mechanical reasons a confident number can be the wrong number. - Filtering delivery state in the wrong case.
deliverytakes lowercase values andeffective_statustakes uppercase. Nothing corrects this for you. - Reading cost per result as cost per acquisition.
cost_per_resultis defined by the objective you selected when you built the campaign;cost_per_omni_purchaseis defined by the purchase event. Across campaigns with different objectives, the first column is not comparable with itself. - Accepting a substitute for a metric with no field. ThruPlay, hook rate and quality ranking have no entry. If an answer contains them anyway, the number was derived from something else, and you need to know from what.
Try this tonight Write down the metric names you use in your own weekly review — the words, exactly as you say them — and ask Claude to look up each one in the field catalogue and show you the canonical name and the levels for each. Anything that returns unknown gets replaced in your saved prompt with the canonical name from the entry beside it. That edit takes one evening and it is permanent: every report you run after it asks for the field you meant rather than the nearest one the assistant could find.
Does an unknown field mean Meta does not have that metric?
No. The catalogue is the set of names this connector accepts, not the Marketing API's full field surface. ThruPlay exists in Meta's reporting; it is not exposed here under a name that resolves. The correct conclusion is that the connector cannot answer it, not that the metric is fictional.
Why do replies say “Meta Accounts” instead of people?
Because the field description instructs it. reach carries the note that when
replying you should use the metric name Reach and, “for units, do not use
people, instead use Meta Accounts”. Several metric descriptions carry
similar presentation rules. The wording that reads as machine-generated is being dictated by the
catalogue.
Can I see the whole list?
Yes. The schema is explicit that omitting the field-names argument returns every field in the catalogue. It is long, so it is more useful as a one-off read than as something to paste into a prompt, and it is the fastest way to find out whether a metric you rely on is even addressable here.
Is this the same thing as the tool list?
No, and they answer different questions. The tool manifest tells you what operations exist; the field catalogue tells you what words those operations accept as arguments. Getting connected in the first place is covered in the setup guide.
One caveat about how this was checked. Everything above comes from the tool's own schema and from field-catalogue lookups run on 2026-09-07 — the tool that defines names, asked about names. No ad account was queried and no account data appears here, so nothing on this page describes what any account contains. Catalogues also change, and this one carries no version string, so a name that resolves today is worth re-checking the next time a report comes back looking odd.
Ask for the field you meant
The course is the operator routine: canonical field names, prompts that state them, and a habit of checking the answer against Ads Manager before it becomes a decision.
See what's inside — $67 founding pricePre-sale: the modules are still being recorded and founding members get the checkout link first. No charge today. Public price $97.