Live read: List an advertiser’s ads
Available on: 
Asks the provider for the ads 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.
Send adGroupId to read one ad group’s ads, or campaignId to read every ad of a campaign whatever ad group holds it.
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/ads?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/ads?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}/adsAuthorizationBearer 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.
advertiserIdstringrequiredidsstringcursorstringlimitintegerstatusstringACTIVEPAUSEDDELETEDARCHIVEDcampaignIdstringadGroupIdstringThe matching ads 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
objectadvertiserIdstringrequiredThe advertiser that owns it, prefixed acc_.
createdAtnumber | nullrequiredWhen AdCrunch first stored this row. Null when the row was read live: 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. 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.
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.
ACTIVEPAUSEDDELETEDARCHIVEDupdatedAtnumber | 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.
adGroupIdstring | nullrequiredThe ad group that holds the ad, as the bare id its provider gives. Null only when the stored path of the row names no ad group.
campaignIdstring | nullrequiredThe campaign it belongs to, as the bare id its provider gives. Null only when the stored path of the row names no campaign.
typestringrequiredThe type the provider uses, kept as the provider writes it: ad at Meta and TikTok, and ad_group_ad at Google Ads. The resource names the concept, and the row keeps the provider’s own word, because a Meta adset and a Google Ads ad_group are not the same object.
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.