Stats
One call gives you the numbers for a date range: results by status, by platform and by day, credits used, what is queued next, and the errors you hit most. Use it for a client report or a health check on your own dashboard.
Updated
GET /v1/stats
Query parameters: from and to (ISO 8601, on each result's scheduled_at; default the last 31 days up to tomorrow) and account_id to report on one account.
bash
curl "https://ugcapi.dev/v1/stats?from=2026-11-01&to=2026-12-01" -H "Authorization: Bearer ugc_live_..."json
{
"from": "2026-11-01T00:00:00.000Z",
"to": "2026-12-01T00:00:00.000Z",
"deliveries": { "published": 412, "failed": 6, "scheduled": 80 },
"by_platform": { "tiktok": { "published": 220, "failed": 4 }, "instagram": { "published": 192, "failed": 2 } },
"by_day": [{ "day": "2026-11-01", "published": 14 }, { "day": "2026-11-02", "published": 15, "failed": 1 }],
"credits_used": 412,
"upcoming": 80,
"next_at": "2026-12-01T17:00:00.000Z",
"top_errors": [{ "error": "Instagram: The media could not be fetched from this URL.", "count": 3 }],
"engagement": { "views": 184200, "likes": 9310, "comments": 412, "shares": 655, "saves": 380, "reach": 120400, "posts_measured": 398, "by_platform": { "instagram": { "views": 70100 } } },
"top_posts": [{ "post_id": "post_abc", "platform": "tiktok", "username": "creator_one", "url": "https://www.tiktok.com/@creator_one/video/123", "caption": "POV: …", "metrics": { "views": 48200, "likes": 2900 } }]
}What the numbers mean
- deliveries counts results, not posts: one post to three accounts is three results.
- credits_used is credits spent minus refunds in the range.
- upcoming and next_at cover everything still scheduled, whatever the range.
- top_errors lists the five most common failure messages, so you can spot an expired login or a media problem early.
- engagement totals views, likes, comments, shares, saves and reach read back from the platforms for published posts, and top_posts lists the five with the most views. Instagram numbers come from Instagram insights; TikTok numbers from TikTok's video list. They refresh hourly;
POST /v1/metrics/refreshreads them again now (at most every 5 minutes). Each result inGET /v1/posts/:idcarries its ownmetricsandmetrics_at.
FAQ
Does it include views or likes?
Yes. Views, likes, comments, shares, saves and reach are read from Instagram and TikTok for published posts and refreshed hourly.
Can I get stats per creator?
Yes. Pass account_id, or call GET /v1/posts with account_id and count the results yourself.