Live read: Get one ad
Available on: 
Asks the provider for one ad now, and gives its payload with the field names of the provider.
The keys are the provider’s. A Meta ad answers id, name, campaign_id, adset_id, status and a creative that holds one key, the creative id. A Meta ad that has a bid of its own also answers bid_amount. A TikTok ad answers ad_id, ad_format, call_to_action, landing_page_url, video_id and image_ids. A Google Ads ad_group_ad answers id, name, status, adGroupId and campaignId.
The payload holds the fields AdCrunch asks the provider for, and no more. Read the creative under /observe/{advertiserId}/creatives for the material a Meta ad runs.
Money
AdCrunch changes one thing in the payload: the money of Meta, bid_amount. Meta writes each amount in a unit that depends on the currency. This read gives each one as a number in whole units of the currency of the advertiser. It is the unit of budget on a row: 250 is 250.00. When AdCrunch does not know the currency of the advertiser, each of these fields is null.
A TikTok amount is in whole units already, so it does not change. A Google Ads field whose name ends in Micros states its unit, so it stays in micros: 12340000 is 12.34.
When there is nothing to give
404 — the provider holds no such ad on this ad account, the provider has no ad at all, or your organization does not own the advertiser in the path. They are deliberately not told apart: distinguishing them would confirm that a ad exists to somebody who cannot read it.
/observe/{advertiserId}/ads/{id}AuthorizationBearer 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.
advertiserIdstringrequiredidstringrequiredThe payload the provider holds now, with the money of Meta in whole units.
anyThe 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.
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.
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.
The provider holds no such entity on this ad account, the provider does not have this kind of entity, or your organization does not own the advertiser in the path. They are deliberately not told apart. error is not_found.
errorstringrequiredA stable code for the failure. This is the field to branch on. It does not change for a given failure.
not_foundmessagestringrequiredA 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.