List an advertiser’s ad groups
Lists the ad groups of one ad account, newest first.
The same rows as the portfolio listing, narrowed to the advertiser the path names. An advertiser your organization does not own answers an empty list, not a failure.
Send campaignId to read one campaign’s ad groups.
/observe/{advertiserId}/ad-groupsAuthorizationBearer token · headerrequiredSend Authorization: Bearer <credential>. Two credentials work.
An API key (acr_…) is what a server integration uses. Create one in the AdCrunch console under Settings → API keys — see https://docs.adcrunch.dev/account/api-keys. A key is bound to the organization that was active when you created it, and it keeps acting on that organization whatever you do later. It carries the permissions of the member who created it.
A session issued by the AdCrunch sign-in flow also works, which is how the console calls this service from the browser.
Either way the organization comes from the credential. There is no organization parameter.
advertiserIdstringrequiredidsstringlimitintegeroffsetintegerstatusstringACTIVEPAUSEDDELETEDARCHIVEDfreshbooleancampaignIdstringThe matching ad groups of this advertiser. An advertiser your organization does not own answers an empty list.
dataobject[]requiredThe matching rows, newest first by the provider’s own created time. An empty array means nothing matched, which is a normal answer and not a failure.
Show propertiesHide properties
objectadGroupIdstring | nullrequiredThe ad group that holds it, as the bare id its provider gives. Null on everything an ad group does not hold: a campaign, an ad group itself, an asset group, and a creative.
advertiserIdstringrequiredThe ad account that owns it, prefixed acc_.
budgetnumber | nullrequiredThe budget this entity carries itself, in whole units of currency: 50 is 50.00, never 50 cents. It is the unit of spend on an Insight, so a budget and a spend compare directly. AdCrunch converts each provider’s own unit — Meta’s minor unit, TikTok’s whole units and Google Ads’ micros — so every provider answers the same unit here.
Null when the entity carries no budget of its own: budgetLevel then says where its budget lives. A campaign answers a budget only when its budgetLevel is campaign, so a budget always paces delivery at the level that answers it. Null also when AdCrunch does not know the account currency yet, because nobody can read a budget with no currency.
At Google Ads one budget may be shared by several campaigns, and each of them answers the whole shared amount.
A stored budget can be older than the rest of the row. Meta does not mark a campaign changed when only its budget changes, and AdCrunch does not yet follow a Google Ads budget change, so the ingestion can miss a budget edited in the provider’s own interface. Send fresh=true on an account-scoped listing to read the budget the provider holds now.
The Mutation API takes a Meta budget in integer minor units, not in whole units. Convert a budget you read here before you write it back.
budgetLevelstring | nullrequiredWhere the budget of this entity’s campaign lives. campaign when the campaign carries it — Meta Advantage campaign budget, TikTok Campaign Budget Optimization, and every Google Ads campaign. ad_group when each ad group carries its own. It answers on campaigns and on everything the ad-groups and asset-groups listings read; it is null on ads and creatives, and on a TikTok campaign whose payload does not say.
campaignad_groupbudgetTypestring | nullrequireddaily for a budget spent each day, lifetime for one spent over the whole life of the entity. Null exactly when budget has no provider value to describe.
dailylifetimecampaignIdstring | nullrequiredThe campaign it belongs to, as the bare id its provider gives. Null on a campaign itself, and on a creative, which belongs to the advertiser rather than to any one campaign.
createdAtnumber | nullrequiredWhen AdCrunch first stored this row. Null when the row was read live — source is then provider, and AdCrunch holds no copy of it. createdAt, updatedAt and deletedAt are AdCrunch’s own times, so all three are null together on a live row.
createdTimenumber | nullrequiredWhen the provider created the entity. This is the provider’s own time, so a live row carries it. Null where the provider reports none.
currencystring | nullrequiredThe account currency, ISO 4217 — the currency budget is in. Every row of one advertiser carries the same one. Null when AdCrunch does not know it yet.
deletedAtnumber | nullrequiredWhen AdCrunch marked the row deleted. A listing never carries a deleted row, so this is null.
idstringrequiredThe id the provider gives, with no prefix. It is unique for one provider and one type, and it may legitimately recur across two types or two providers.
namestringrequiredThe name at the provider.
objectivestring | nullrequiredThe campaign’s objective, kept as the provider writes it: Meta OUTCOME_SALES, TikTok TRAFFIC. It is the provider’s word, for the same reason type is. Null on everything that is not a campaign, and on every Google Ads campaign, because Google Ads has no objective.
pathstringrequiredThe ancestors and this entity, ids joined by /, oldest first. This is what makes a subtree one string comparison.
providerstringrequiredThe ad platform: meta, tiktok, gads, snapchat or dv360.
statusstringrequiredThe status, normalized across the providers. TikTok ENABLE and DISABLE read here as ACTIVE and PAUSED.
ACTIVEPAUSEDDELETEDARCHIVEDtypestringrequiredThe type the provider uses, kept as the provider writes it: campaign, adset at Meta, ad_group at TikTok and Google Ads, asset_group, ad, creative. The path names the concept; the row keeps the provider’s own word, because a Meta adset and a Google ad_group are not the same object.
updatedAtnumber | nullrequiredWhen AdCrunch last rewrote this row. Null if it never changed.
updatedTimenumber | nullrequiredWhen the provider last edited the entity. Null where the provider reports none.
paginationobjectrequiredShow propertiesHide properties
limitnumberrequiredThe greatest number of rows this answer can carry.
offsetnumberrequiredThe number of rows skipped before the first.
totalnumber | nullrequiredHow many rows match, over every advertiser read. It counts the whole match and not this page, so offset + limit reaching total means there is no more to read. Null on a live page whose provider reports no count — Google Ads never does — and a number everywhere else.
sourcestringrequiredWhich side answered. store is what AdCrunch holds, which its ingestion refreshes. provider is a live read of the provider itself, which an account-scoped listing answers when you send fresh=true.
storeproviderNo credential, or one that does not resolve. Send an API key or a session. See the security scheme. error is unauthorized.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
unauthorizedmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
The caller does not hold observe:read. error is forbidden.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
forbiddenmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
This advertiser has no usable connection to its provider. A person must reconnect it; the same read without fresh still answers what AdCrunch holds.
providerstringrequiredThe ad platform this failure came from: meta, tiktok, gads, snapchat or dv360.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
provider_not_connectedmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
The request did not match this operation’s schema. This is the framework’s own shape, not the error/message one.
errorsobject[]requiredOne entry per failing field.
foundanyrequiredWhat was sent.
messagestringrequiredonstringrequiredWhich part of the request failed: body, query or params.
propertystringrequiredThe field that failed.
typestringrequiredvalidationAdCrunch cannot read this resource live from this advertiser’s provider. It is permanent — read the same resource without fresh.
providerstringrequiredThe ad platform this failure came from: meta, tiktok, gads, snapchat or dv360.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
live_read_unsupportedmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
The provider refused the request, or could not answer it. Often transient, so a retry is worth making.
platformErroranyrequiredThe provider’s own error object, unchanged. For Meta it carries code, error_subcode, type, error_user_title and error_user_msg — branch on the subcode for anything AdCrunch does not model. It never holds the request AdCrunch sent.
providerstringrequiredThe ad platform this failure came from: meta, tiktok, gads, snapchat or dv360.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
provider_errormessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.