Stored read: List ad groups
Available on: 
Lists the ad groups of every ad account your organization connects, across the providers, newest first.
One concept, three words
An ad group is a Meta ad set, a TikTok ad group and a Google Ads ad group. This path reads all three at once, and every row keeps the word its own provider writes, in type. AdCrunch renames nothing: a Meta adset and a Google ad_group are not the same object, and a caller that must speak to the provider needs the provider’s word.
Narrowing
Send campaignId to read one campaign’s ad groups, and provider to read one platform. limit counts rows of the answer itself, not rows of each advertiser. When the answer holds nextCursor, more rows exist: send it back as cursor to get the next page.
Budget
An ad group that carries its own budget answers it in budget, in whole units of its currency, and a budgetLevel of ad_group. One whose campaign carries the budget answers a null budget and a budgetLevel of campaign: read the campaign for the amount. Every Google Ads ad group is the second kind, because Google Ads keeps every budget on the campaign.
What is not here
Performance Max campaigns have no ad groups. Google’s automation delivers them through an asset group instead, which is a child of the campaign and a sibling of an ad group — so a Performance Max campaign answers nothing here, and that is not a fault. Read /observe/asset-groups for those.
/observe/ad-groupsAuthorizationBearer token · headerrequiredSend Authorization: Bearer <credential>.
Use an API key (acr_…), from the AdCrunch console under Settings → API keys.
The credential names the organization, and no operation takes an organization parameter.
See https://docs.adcrunch.dev/api/authentication.
idsstringcursorstringlimitintegeradvertiserIdstringproviderstringstatusstringACTIVEPAUSEDDELETEDARCHIVEDcampaignIdstringThe matching ad groups, and how many there are in all. Each row keeps its provider’s own type: adset, adgroup or ad_group.
dataobject[]requiredThe matching rows. From the store, the row AdCrunch stored last comes first; from the provider, the provider’s own order. 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 advertiser 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. Read the advertiser’s own path, /observe/{advertiserId}/campaigns, for the budget the provider holds now.
The Mutation API takes a budget in the same whole units, so a budget you read here goes back with no conversion.
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, on a path that names the advertiser: 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 or gads. Those three are the providers whose entities AdCrunch reads, and https://docs.adcrunch.dev/connect/providers says how deep each one goes.
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.
nextCursorstringSend this value as cursor to get the next page. It is absent on the last page.
The request does not match the schema of this operation: a field is missing or has the wrong type, or the body is not valid JSON. error is invalid_request, and issues names each field. Nothing was changed. Or AdCrunch cannot use the cursor: it cannot read it, or the cursor belongs to a different query. Then error is invalid_cursor. Send the nextCursor of the previous page with no change, or omit cursor to get the first page.
issuesobject[]requiredOne entry for each field that does not match.
Show propertiesHide properties
objectinstringrequiredThe part of the request that holds the field.
bodycookieheadersparamsquerymessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
pathstringrequiredA JSON Pointer into that part of the request, such as /filename. An empty string is the whole part.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
invalid_requestmessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
invalid_cursormessagestringrequiredA sentence to show a person. Written to say what to do next. Reworded whenever it can be said better, so never branch on it.
No API key, or one that does not resolve. 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.