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 that your organization does not own answers 404, with error of not_found. An advertiser that does not exist answers the same. The answer does not tell the two apart.
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 |
Request
- Base URL: https://api.adcrunch.dev
- URL: https://api.adcrunch.dev/observe/{advertiserId}/ads
- Auth: HTTP bearer
Path parameters
The ad account to read, prefixed acc_. It must belong to your organization. One that does not answers 404, with error of not_found.
Query parameters
Ids to filter on, separated by commas. An id is the bare id its provider gives.
The nextCursor of the previous page. Omit it to get the first page. Send it with no change, and with the same filters as the request that answered it: a cursor from a different query gets a 400 invalid_cursor. Do not build or change a cursor.
The greatest number of rows on the page, from 1 to 500. The default is 100. A greater value gets a 400, with error of invalid_request.
Read one status, normalized across the providers: the status the entity is set to, not whether it delivers. Every row of the answer carries this status. A provider that cannot select this status exactly answers 501; the description of this operation lists what each provider selects.
Read only what this campaign holds. Send the bare id its provider gives, which is the campaignId every row answers.
Read only what this ad group holds. Send the bare id its provider gives, which is the adGroupId every row answers.
Response
The matching ads of this advertiser.
Example response
{
"data": [
{
"adGroupId": "120210000000001",
"advertiserId": "acc_1203456789012345",
"campaignId": "120210000000000",
"createdAt": null,
"createdTime": 1789600000000,
"currency": "EUR",
"deletedAt": null,
"id": "120210000000002",
"name": "Carousel — bestsellers",
"path": "120210000000000/120210000000001/120210000000002",
"provider": "meta",
"status": "ACTIVE",
"type": "ad",
"updatedAt": null,
"updatedTime": 1789900000000
}
],
"nextCursor": "eyJwIjp7ImFmdGVyIjoiUVZGSVVteFpBVmhSUTJ0QlVXdFIiLCJwcm92aWRlciI6Im1ldGEifSwicSI6IjFwc2sxcGFja3VlIiwibCI6dHJ1ZX0"
}Changes
No recorded changes to this operation across all 1 revision of this API.