Live read: List an advertiser’s campaigns
Available on: 
Asks the provider for the campaigns of one ad account, now. This is a live read: the path names the advertiser, so the answer is what the provider holds, not what AdCrunch holds.
An advertiser your organization does not own answers an empty list, not a failure.
A live row carries no createdAt, updatedAt or deletedAt, because AdCrunch stores nothing for it. Each request counts against the rate limits of the provider.
For the stored rows of the same advertiser, read /observe/campaigns?advertiserId=…. That path takes every status, and the Status section below lists the statuses this one takes.
limit and cursor page the answer. Send nextCursor back as cursor to get the next page. A live cursor is good only for a live read. At TikTok, every page keeps the page size of the first.
Status
status selects the status an entity is set to, not whether it delivers, and every row of the answer carries it. A provider takes a status only where one request to it selects exactly the entities in that status. Any other status answers 501.
The stored read, /observe/campaigns?advertiserId=…&status=…, takes every status. A status that a provider never uses answers an empty list.
| Provider | Takes status |
|---|---|
| Meta | none yet |
| TikTok | DELETED, ARCHIVED |
| Google Ads | ACTIVE, PAUSED, DELETED, ARCHIVED |
/observe/{advertiserId}/campaignsAuthorizationBearer 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.
advertiserIdstringrequiredidsstringcursorstringlimitintegerstatusstringACTIVEPAUSEDDELETEDARCHIVEDThe matching campaigns of this advertiser. An advertiser your organization does not own answers an empty list.
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.
This advertiser has no usable connection to its provider. A person must reconnect it. The stored read of the same resource, with advertiserId, still answers what AdCrunch holds.
providerstringrequiredThe ad platform this failure came from: meta, tiktok or gads.
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.
AdCrunch cannot read this resource live from this advertiser’s provider. It is permanent. Read the stored copy instead, at the same resource without the advertiser in the path and with advertiserId.
providerstringrequiredThe ad platform this failure came from: meta, tiktok or gads.
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 or gads.
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.