Curator API: Get Ads
GET https://api.curator.io/v1.3/ads returns the ads in your Curator account as JSON, one page at a time. Ads are your own posts that appear at set positions in a feed. The request needs your API key, and your plan must include API access. Only HTTPS is supported.
Authentication
Send your Curator API key (find it in the Curator Dashboard) in one of three ways: as a query string (?api_key=API_KEY), as a Basic auth header with the API key as the username, or as a Bearer token (Authorization: Bearer API_KEY, with Bearer capitalised). The key decides which account you are working in; you only see that account's ads.
Example request
curl "https://api.curator.io/v1.3/ads?feed_id=FEED_ID&status=active" \
-H "Authorization: Bearer API_KEY"Parameters
Parameter | Description |
|---|---|
| Only ads in this feed, by the feed's API ID. |
|
|
| Ads per page, between 1 and 100. Default 15. |
| Cursors from |
Response
A 200 response has the ads in data, oldest first, and paging details in meta.pagination. Ads in deleted feeds are left out. There is no endpoint for a single ad, so use this list.
{
"data": [
{
"id": "8xjopdw6",
"feed_id": "FEED_ID",
"network_id": 3,
"status": "paused",
"name": "Summer sale",
"title": "T",
"text": "<b>hi</b>",
"image": "https://example.com/a.png",
"video": "",
"is_html": true,
"click_action": "goto-url",
"position_start": 3,
"position_repeats": true,
"position_repeat_interval": 7,
"image_width": 300,
"image_height": 200,
"url": "https://example.com",
"created_at": "2026-11-20T03:31:07.000000Z",
"slug": "8xjopdw6",
"network_name": "Facebook"
}
],
"meta": {
"success": true,
"pagination": { "per_page": 15, "after": null, "before": null, "after_link": null, "before_link": null }
}
}Paginating with cursors
Follow meta.pagination.after_link for the next page and before_link for the previous one. The links keep your filters but leave out api_key, so send the key in a header or add it again. after is null on the last page and before is null on the first.
Ad object
Field | Description |
|---|---|
| The ad's ID, a short code such as |
| API ID of the feed the ad appears in. |
|
|
| The ad's internal name. |
| The ad's title and text, and whether the text is HTML. |
| Image and video URLs, or empty. |
| Image size in pixels. |
|
|
| The position in the feed where the ad first appears. |
| Whether the ad repeats, and how many posts apart. |
| The network the ad is styled as, or |
| When the ad was created, in UTC. |
Errors
Errors use the same wrapper, with data set to null and the reason in meta.message.
Status | When | Body |
|---|---|---|
400 | Both |
|
401 | The API key is missing or not valid. |
|
403 | Your plan does not include API access. |
|
404 | No feed in your account matches |
|
422 |
|
|
429 | When rate limiting is enabled, more than 60 requests per minute. |
|