Brand key required
Content tracking
Add post URLs (or a whole creator handle) and Roster keeps views, likes, comments, shares, and saves fresh on a recurring refresh, with history, per-post refresh on demand, and an aggregate report.
List tracked posts
GET/v1/content
| Parameter | Type | Description |
|---|---|---|
| platform | string | Filter: instagram, tiktok, youtube. |
| status | string | Filter: active, pending, error, excluded. |
| page / limit | integer | Standard pagination. |
request
curl "https://api.ugcroster.com/v1/content?platform=tiktok" \
-H "Authorization: Bearer rsk_brand_key"response 200
{
"data": [
{
"id": "post_001",
"url": "https://www.tiktok.com/@emmachen/video/123456",
"platform": "tiktok",
"creator_name": "Emma Chen",
"creator_handle": "emmachen",
"campaign_id": "form_xyz789",
"thumbnail_url": "https://…",
"caption": "My honest fall skincare routine",
"metrics": {
"views": 142000, "likes": 8400, "comments": 312,
"shares": 1200, "saves": 890, "engagement_rate": 7.6
},
"added_at": "2026-06-08T14:00:00Z",
"last_fetched_at": "2026-06-13T06:00:00Z",
"status": "active",
"error": null
}
],
"pagination": { "page": 1, "limit": 20, "total": 67, "has_more": true },
"summary": {
"total_views": 1240000, "total_likes": 88200,
"total_comments": 4100, "post_count": 67
}
}New posts start with status: "pending" and null metrics until the first fetch completes. The summary block excludes excluded posts and avoids double-counting profile-level aggregates.
Track a post
POST/v1/content
| Field | Type | Description |
|---|---|---|
| url | string | Required. Post URL. Platform and creator handle are detected from it. |
| creator_name | string | Optional label. |
| campaign_id | string | Optional campaign linkage. |
request
curl -X POST "https://api.ugcroster.com/v1/content" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "url": "https://www.instagram.com/reel/abc123", "creator_name": "Emma Chen", "campaign_id": "form_xyz789" }'response 200
{ "data": { "id": "post_new001", "url": "https://www.instagram.com/reel/abc123", "platform": "instagram", "status": "pending" } }An initial metrics fetch is kicked off immediately; check back or force a refresh below.
Get, refresh, delete a post
GET/v1/content/{id}
Same shape as a list item plus metrics_history, an array of dated snapshots for charting growth.
POST/v1/content/{id}
Body must be { "action": "refresh" }. The refresh runs synchronously and returns fresh numbers.
request
curl -X POST "https://api.ugcroster.com/v1/content/post_001" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "action": "refresh" }'response 200
{
"data": {
"id": "post_001",
"status": "active",
"views": 143550, "likes": 8460, "comments": 315,
"shares": 1210, "saves": 902, "engagement_rate": 7.61
}
}DELETE/v1/content/{id}
response 200
{ "data": { "id": "post_001", "deleted": true } }Bulk import by handle
POST/v1/content/import
Imports a creator’s recent posts from a single handle instead of adding URLs one at a time. Already-tracked URLs are skipped, so it is safe to run repeatedly. The handle is also added to a watchlist so new posts keep getting picked up automatically.
| Field | Type | Description |
|---|---|---|
| handle | string | Required. Creator handle, with or without @. |
| platform | string | Required: instagram or tiktok. |
| creator_name | string | Optional label applied to imported posts. |
| campaign_id | string | Optional campaign linkage. |
| limit | integer | Max recent posts to scan. Default 50, max 100. |
request
curl -X POST "https://api.ugcroster.com/v1/content/import" \
-H "Authorization: Bearer rsk_brand_key" \
-H "Content-Type: application/json" \
-d '{ "handle": "emmachen", "platform": "tiktok", "campaign_id": "form_xyz789", "limit": 30 }'response 200
{
"data": {
"handle": "emmachen",
"platform": "tiktok",
"found": 30,
"added": 12,
"skipped_existing": 18,
"added_urls": ["https://www.tiktok.com/@emmachen/video/…"]
}
}Aggregate report
GET/v1/content/report
response 200
{
"data": {
"total_posts": 67,
"active_posts": 61,
"total_views": 1240000,
"total_likes": 88200,
"total_comments": 4100,
"total_shares": 9800,
"total_saves": 7300,
"avg_engagement_rate": 0.0823,
"platform_breakdown": {
"tiktok": { "posts": 40, "views": 910000, "likes": 61000, "comments": 2900 },
"instagram": { "posts": 21, "views": 330000, "likes": 27200, "comments": 1200 }
},
"top_creators": [ { "handle": "emmachen", "views": 412000 } ]
}
}