Documentation / Campaign management

Campaign media

Track media, manage creator content, and read performance metrics via /sdk/v1.

campaign media · json
{
  "success": true,
  "data": [
    {
      "campaignCreatorMediaId": "ccm_...",
      "mediaUrl": "https://www.tiktok.com/@creator/video/7350000000000000000",
      "platform": "tiktok",
      "mediaType": "post",
      "isSlideshow": true,
      "authorUsername": "creator",
      "authorDisplayName": "Creator Name",
      "title": "Launch video",
      "captionText": "Our spring launch",
      "hashtags": ["springlaunch", "partner"],
      "audioTitle": "Original sound",
      "audioArtist": "Creator Name",
      "audioIsOriginal": true,
      "views": 5000,
      "likes": 320,
      "comments": 15,
      "shares": 8
    }
  ],
  "metrics": {
    "trackedMediaCount": 12,
    "trackedPostCount": 10,
    "trackedAccountCount": 2,
    "uniqueCreatorsCount": 3,
    "totalViews": 25000,
    "totalLikes": 1200,
    "totalComments": 80,
    "totalShares": 45,
    "totalBookmarks": 30
  },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z"
}
All documentation

All endpoints below require:

  • X-Application-Id
  • X-Api-Key

Media can be added and tracked independently of contracts. You do not need to set up a contract before tracking a creator's media.

To keep warm-up posts tracked while excluding them from fixed-rate or CPM and bonus calculations, see Payment exclusions. The API supports both exclusion and undo for posts and tracked accounts.

To read or update eligibility scores for tracked posts, see List eligibility scores and Update eligibility scores.

To list groups by campaign-creator ID, inspect their members, or correct grouping, see Crosspost groups.

GET /sdk/v1/campaigns/:campaignId/media

List all tracked media across the campaign with aggregate metrics.

For integrations that maintain a local copy, use Sync campaign media to download bounded pages initially and then receive changed records and removals.

Query parameters

  • query (optional; searches creator display names)
  • platform (optional; filter by platform, e.g., instagram, tiktok, youtube)

Response

{
  "success": true,
  "data": [
    {
      "campaignCreatorMediaId": "ccm_...",
      "mediaUrl": "https://www.tiktok.com/@creator/video/7350000000000000000",
      "platform": "tiktok",
      "mediaType": "post",
      "isSlideshow": true,
      "authorUsername": "creator",
      "authorDisplayName": "Creator Name",
      "title": "Launch video",
      "captionText": "Our spring launch",
      "hashtags": ["springlaunch", "partner"],
      "audioTitle": "Original sound",
      "audioArtist": "Creator Name",
      "audioIsOriginal": true,
      "views": 5000,
      "likes": 320,
      "comments": 15,
      "shares": 8
    }
  ],
  "metrics": {
    "trackedMediaCount": 12,
    "trackedPostCount": 10,
    "trackedAccountCount": 2,
    "uniqueCreatorsCount": 3,
    "totalViews": 25000,
    "totalLikes": 1200,
    "totalComments": 80,
    "totalShares": 45,
    "totalBookmarks": 30
  },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z"
}

When the platform actor supplies it, campaign media rows include normalized author fields (authorPlatformId, authorUsername, authorDisplayName), content fields (title, captionText, hashtags), audio fields (audioPlatformId, audioTitle, audioArtist, audioAlbum, audioIsOriginal), and metadataCollectedAt. Unavailable fields are null, and hashtags is an empty array when none are available.

Account check warnings

Account media rows include accountIssue, independently of tracking tier. It is null when no warning is recorded, including before the first check. A successful completed check clears it. Do not render an “OK” badge or treat null as proof that all historical posts were discovered.

{
  "accountIssue": {
    "code": "CHECK_FAILED",
    "reasonCode": "INCOMPLETE_RESPONSE",
    "message": "The provider did not finish retrieving this account.",
    "checkedAt": "2026-10-19T04:05:00.000Z"
  }
}
Code Meaning
PROFILE_NOT_FOUND The provider explicitly reported that the profile does not exist. Check its link or username.
PROFILE_PRIVATE The provider explicitly identified a private profile.
NO_ACCESSIBLE_VIDEOS No public posts could be retrieved. This may include a login wall; it does not prove the creator has never posted.
CHECK_FAILED The check could not finish reliably. Use reasonCode and message to explain why.

CHECK_FAILED reasons are ACCESS_BLOCKED, RATE_LIMITED, TIMEOUT, INCOMPLETE_RESPONSE, INVALID_RESPONSE, PROCESSING_FAILED, PROFILE_UNAVAILABLE, PROVIDER_UNAVAILABLE, and PROVIDER_ERROR. Other codes have a null reason. PROCESSING_FAILED identifies a Grade-side failure to prepare the check or process its results, including an invalid account target or missing tracking dates. Messages are safe for display; use codes for application logic.

checkedAt is the UTC time of the reported issue. The previous warning remains while a new check is pending. An empty date-filtered window is not an account warning, and a failed individual post does not label its parent account missing or private. Results are scoped to each account, including when several accounts share a provider run. Providers include Apify actors and the official X API.

Temporary CHECK_FAILED results remain internal while automatic recovery is pending. If recovery succeeds, no new warning appears. If recovery finishes unsuccessfully, Grade publishes the issue and its reason. Failures with no remaining automatic recovery can be published immediately. Explicit profile availability responses do not wait for technical retries.

The official X API continues retrying without a fixed attempt limit. Its first transient failure stays internal; a subsequent failure at least three hours later publishes CHECK_FAILED if the account check still has not completed. Retries continue, and a successful completed check clears the warning.

Instagram account checks combine the required posts and reels providers. Neither provider can clear a warning while the other is pending or recovering. Conflicting availability responses become CHECK_FAILED with INCOMPLETE_RESPONSE; Grade does not assert that a profile is private or missing when another required provider succeeds. A successful posts check with no accessible reels does not itself produce a warning.

GET /sdk/v1/campaigns/:campaignId/creators/media

List a campaign creator's tracked media, broken down into accounts and posts.

Query parameters

  • email (required)
  • includeGroups (optional; true to include explicit group rows)
  • page (default 1)
  • limit (default 5)

Response

{
  "success": true,
  "data": {
    "creatorEmail": "creator@example.com",
    "creatorProfileId": "cp_...",
    "campaignCreatorRecordId": "ccr_...",
    "accounts": [
      {
        "campaignCreatorMediaId": "ccm_...",
        "mediaUrl": "https://www.instagram.com/creatorhandle",
        "platform": "instagram",
        "mediaType": "account",
        "isSlideshow": null
      }
    ],
    "posts": [
      {
        "campaignCreatorMediaId": "ccm_...",
        "mediaUrl": "https://www.tiktok.com/@creator/video/7350000000000000000",
        "platform": "tiktok",
        "mediaType": "post",
        "isSlideshow": true,
        "authorUsername": "creator",
        "captionText": "Our spring launch",
        "hashtags": ["springlaunch", "partner"],
        "audioTitle": "Original sound",
        "views": 5000,
        "likes": 320,
        "comments": 15,
        "shares": 8
      }
    ]
  },
  "pagination": {
    "accounts": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 },
    "posts": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 }
  },
  "asOfTimestamp": "2026-03-03T12:00:00.000Z"
}

When includeGroups=true, the response includes an additional groups array and pagination.groups object. Group rows also include isSlideshow when the winning media item has a known slideshow state. Normalized author, content, hashtag, and audio metadata on a group row comes from that group's winning media item.

Common errors

  • 400: missing email
  • 404: creator not found in this campaign

POST /sdk/v1/campaigns/:campaignId/creators/media

Add or update tracked media for a campaign creator. If the creator is not yet a member of the campaign, they are automatically added (implicit membership).

Background scraping is triggered automatically after media is saved.

Body

{
  "email": "creator@example.com",
  "media": [
    {
      "mediaUrl": "https://www.instagram.com/creatorhandle",
      "platform": "instagram",
      "startDate": "2026-03-01T00:00:00.000Z",
      "trackForValue": 7,
      "trackForUnit": "DAYS"
    }
  ]
}
email string body required

Creator email address.

media array body required

Array of media items to track.

Each item in the media array accepts:

media[].mediaUrl string body required

URL of the post or account to track.

media[].platform string body

Platform name (e.g., instagram, tiktok, youtube). Optional if the platform can be derived from the URL.

media[].startDate string body

Optional ISO date when tracking starts. If omitted, tracking starts at save time.

media[].trackStartAt string body

Backward-compatible alias for startDate.

media[].trackForValue number body

Relative tracking duration for discovered posts. Provide this together with trackForUnit, for example 7 with DAYS.

media[].trackForUnit string body

Relative tracking unit. Must be DAYS or MONTHS when trackForValue is provided.

Relative tracking windows

Use trackForValue and trackForUnit to choose how long each discovered post is tracked after it is uploaded.

Examples:

  • 7-day window: "trackForValue": 7, "trackForUnit": "DAYS"
  • 30-day window: "trackForValue": 30, "trackForUnit": "DAYS"
  • 2-month window: "trackForValue": 2, "trackForUnit": "MONTHS"

For example, if a creator uploads a video on March 1 and you send trackForValue: 7 with trackForUnit: "DAYS", Grade counts the video's views for the first 7 days after upload. If the campaign pays CPM or bonuses after tracking completes, the video becomes payable after that 7-day window is complete.

media[].captionFilter string body

Selects which posts to track from an account-type URL (max 256 characters). Only applies to account media. This does not change crosspost grouping rules. The contract's caption grouping override is a separate setting.

media[].campaignCreatorMediaId string body

Existing media record ID to update. Omit to create a new media entry.

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "creator@example.com",
    "creatorProfileId": "cp_...",
    "campaignCreatorRecordId": "ccr_...",
    "saved": true
  }
}

Common errors

  • 400: missing email or media
  • 400: startDate is invalid
  • 400: endDate and trackEndAt are not supported for creator media. Use trackForValue and trackForUnit for relative tracking windows.
  • 400: trackForValue and trackForUnit must be provided together
  • 400: trackForUnit must be DAYS or MONTHS

DELETE /sdk/v1/campaigns/:campaignId/creators/media

Remove a tracked media item from a campaign creator.

Body

{
  "email": "creator@example.com",
  "campaignCreatorMediaId": "ccm_..."
}

Response

{
  "success": true,
  "data": {
    "campaignId": "camp_...",
    "creatorEmail": "creator@example.com",
    "creatorProfileId": "cp_...",
    "campaignCreatorRecordId": "ccr_...",
    "campaignCreatorMediaId": "ccm_...",
    "removed": true
  }
}

Common errors

  • 400: missing email or campaignCreatorMediaId
  • 404: media item not found

GET /sdk/v1/campaigns/:campaignId/media/discovered-posts

List posts discovered for an account-type media item. When you track an account URL (e.g., https://www.instagram.com/creatorhandle), the system periodically discovers new posts from that account and tracks them automatically.

Query parameters

  • sourceCampaignCreatorMediaId (required; the account media item ID)
  • page (default 1)
  • limit (default 5)
  • startDate / endDate (optional, YYYY-MM-DD; provide both together)
  • performanceWindowDays (optional integer, 1-366)

By default, metric fields such as views return the latest cumulative scrape value. When startDate and endDate are provided, those same fields return the metric delta for that date range, using the latest scrape inside the range minus the latest scrape before the range. When performanceWindowDays is provided, each post uses its own uploadDate as the window start and returns the metric delta for the first N days after that upload.

Use either startDate / endDate or performanceWindowDays, not both. Windowed responses also include viewsTotal, likesTotal, commentsTotal, sharesTotal, and metricsWindow so you can distinguish the current cumulative totals from the requested window deltas. If performanceWindowDays is requested but a post does not yet have an uploadDate, window metric fields are null and metricsWindow.status is missingUploadDate.

Response

{
  "success": true,
  "data": [
    {
      "campaignCreatorMediaId": "ccm_...",
      "mediaUrl": "https://www.tiktok.com/@creator/video/7350000000000000001",
      "platform": "tiktok",
      "isSlideshow": false,
      "authorUsername": "creator",
      "captionText": "A newly discovered post",
      "hashtags": ["partner"],
      "audioTitle": "Original sound",
      "views": 1200,
      "likes": 85,
      "comments": 5,
      "uploadDate": "2026-03-01T14:22:00.000Z"
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 3 }
}

Example first-7-days response:

{
  "success": true,
  "data": [
    {
      "campaignCreatorMediaId": "ccm_...",
      "mediaUrl": "https://www.tiktok.com/@creator/video/7350000000000000001",
      "isSlideshow": false,
      "views": 4200,
      "viewsTotal": 8900,
      "uploadDate": "2026-03-01T14:22:00.000Z",
      "metricsWindow": {
        "mode": "performanceWindowDays",
        "days": 7,
        "startAt": "2026-03-01T14:22:00.000Z",
        "endAt": "2026-03-08T14:22:00.000Z",
        "status": "ready",
        "asOfTimestamp": "2026-03-08T12:15:00.000Z"
      }
    }
  ],
  "pagination": { "page": 1, "limit": 50, "totalPages": 1, "totalItems": 1 }
}

Common errors

  • 400: missing sourceCampaignCreatorMediaId
  • 400: startDate and endDate must be provided together
  • 400: performanceWindowDays must be an integer between 1 and 366
  • 400: use either startDate / endDate or performanceWindowDays, not both
  • 404: source media item not found or does not belong to your agency

Describe your program.

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