All documentation
Documentation
All endpoints below require:
X-Application-IdX-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;trueto include explicit group rows)page(default1)limit(default5)
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: missingemail404: 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 requiredCreator email address.
media array body requiredArray of media items to track.
Each item in the media array accepts:
media[].mediaUrl string body requiredURL of the post or account to track.
media[].platform string bodyPlatform name (e.g., instagram, tiktok, youtube). Optional if the platform can be derived from the URL.
media[].startDate string bodyOptional ISO date when tracking starts. If omitted, tracking starts at save time.
media[].trackStartAt string bodyBackward-compatible alias for startDate.
media[].trackForValue number bodyRelative tracking duration for discovered posts. Provide this together with
trackForUnit, for example 7 with DAYS.
media[].trackForUnit string bodyRelative 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 bodySelects 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 bodyExisting 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: missingemailormedia400:startDateis invalid400:endDateandtrackEndAtare not supported for creator media. UsetrackForValueandtrackForUnitfor relative tracking windows.400:trackForValueandtrackForUnitmust be provided together400:trackForUnitmust beDAYSorMONTHS
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: missingemailorcampaignCreatorMediaId404: 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(default1)limit(default5)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: missingsourceCampaignCreatorMediaId400:startDateandendDatemust be provided together400:performanceWindowDaysmust be an integer between 1 and 366400: use eitherstartDate/endDateorperformanceWindowDays, not both404: source media item not found or does not belong to your agency
