All documentation
Documentation
All writes below require campaigns:write. IDs must belong to the API key's agency. Completed campaigns return 409 with code: "CAMPAIGN_COMPLETED"; reopen the campaign before editing. Deleted or retired media cannot be edited, except a soft-deleted row can be restored explicitly.
Refresh an account or post
POST /sdk/v1/campaign-media/:campaignCreatorMediaId/refresh
Use the campaignCreatorMediaId returned by the campaign media API.
An account refresh checks for new posts within its existing tracking settings;
a post refresh updates that post's metrics. Send an empty JSON object or omit
the body. This operation keeps the account's original tracking start date.
curl -X POST "$BASE_URL/sdk/v1/campaign-media/$CAMPAIGN_MEDIA_ID/refresh" \
-H "X-Application-Id: $APP_ID" \
-H "X-Api-Key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{}'
A 200 response confirms the scrape was queued; execution is asynchronous.
{
"success": true,
"data": {
"campaignCreatorMediaId": "CCMEDIA_...",
"campaignId": "CMP_...",
"manualRefreshCount": 1,
"manualRefreshLastRequestedAt": "2026-10-28T10:00:00.000Z",
"refreshLimit": 3,
"refreshCooldownMs": 14400000
}
}
Each account or post shares its allowance with refreshes requested in the app: three manual refreshes total, with a four-hour cooldown after each successfully queued refresh. The count increases only when work is queued.
| Status | Code | Meaning |
|---|---|---|
409 |
CCM_REFRESH_ALREADY_IN_PROGRESS |
A refresh is already running. |
409 |
CCM_REFRESH_LIMIT_REACHED |
All three manual refreshes have been used. |
429 |
CCM_REFRESH_COOLDOWN |
Wait until data.refreshAvailableAt before retrying. |
409 |
CCM_REFRESH_NOT_SUPPORTED |
The media cannot be scraped, for example an uploaded file. |
503 |
CCM_REFRESH_QUEUE_FAILED |
Work could not be queued; no refresh allowance was consumed. |
For standalone tracked content, use tracked-media scrape-now. Campaign media IDs cannot be used with that standalone endpoint.
Freeze and unfreeze performance
POST /sdk/v1/campaign-media/:campaignCreatorMediaId/freeze-performance
{ "notes": "Warm-up period", "pausedAt": "2026-10-01T00:00:00Z" }
Both fields are optional; omitting pausedAt uses the current time. This opens a performance-pause window for CPM and performance bonuses. Tracking continues. Fixed-rate eligibility is controlled by payment exclusions.
POST /sdk/v1/campaign-media/:campaignCreatorMediaId/unfreeze-performance
{ "unpausedAt": "2026-10-15T00:00:00Z" }
Omit unpausedAt to resume at the current time. This closes the pause window; it does not erase its history. The same platform validation and grouped-media rules apply.
Restore deleted media
POST /sdk/v1/campaign-media/:campaignCreatorMediaId/restore with {} restores a soft-deleted row using its original ID and history. Restoring an account also restores its eligible discovered posts under the platform's restore rules. Media limits still apply. Tracking-retired rows cannot be restored through this operation.
Restart account tracking
POST /sdk/v1/campaign-media/:campaignCreatorMediaId/restart-tracking
{ "effectiveFrom": "2026-10-01T00:00:00Z" }
Use an account media ID. This restarts account tracking from the supplied instant using the same history-preserving rules as the platform. It can retire old child posts and schedule account discovery; it is not a generic refresh button. Existing payout and approval protections still apply.
Change account tracking settings
PATCH /sdk/v1/campaign-media/:campaignCreatorMediaId/tracking-settings
{ "trackStartAt": "2026-10-01", "trackForValue": 30, "trackForUnit": "DAYS" }
All three fields are required. trackForUnit is DAYS or MONTHS; trackForValue is a positive integer. The platform applies the settings to the account and eligible child posts while preserving protected history.
Enter manual analytics
PUT /sdk/v1/campaign-media/:campaignCreatorMediaId/manual-analytics
{ "views": 12000, "likes": 650, "comments": 48, "shares": 20, "bookmarks": 10 }
Provide at least one metric. Values must be integers from 0 through 9007199254740991 (JavaScript's maximum safe integer); larger values return 400. Counts above the 32-bit integer limit are supported. Use a post ID, not an account. The operation writes a manual snapshot, recalculates affected summaries, and uses the existing platform rules for omitted metrics. Review the resulting analytics before sending a payout.
Successful writes return { "success": true, "data": ... } with the operation's result and, where applicable, a message. These operations do not send a payout.
