Documentation / Campaign management

Manage campaign media

Refresh campaign accounts and posts, freeze performance payments, restore media, and edit tracking or metrics.

manage campaign media · bash
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 '{}'
All 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.

Describe your program.

Grade turns it into a program it can track and pay.