Skip to main content

​
Endpoint

POST https://api.ugc.inc/stats/refresh

​
Overview

Fetch fresh, real-time statistics directly from TikTok/Instagram API for all accounts in your organization (or a specific org_group). This endpoint creates new stat records in the database with the latest data for each account and all their posts. This is useful when you need up-to-date statistics for multiple accounts without waiting for the scheduled refresh cycle. This endpoint also supports NDJSON streaming progress. Send the X-Stream-Progress: true header to receive line-delimited progress events instead of the standard JSON summary response.
Rate Limit: Stats can only be refreshed once per hour per organization (or per org_group if specified). If you attempt to refresh before the cooldown period has elapsed, you’ll receive an error with details about when the next refresh is allowed.

​
How It Works

  1. Fetches all accounts in your organization (optionally filtered by org_group)
  2. For each account with username and type configured:
    • Fetches account profile stats (followers, following) from the platform API
    • Fetches stats for all posts associated with the account
    • Creates an account_stats record with aggregated post metrics
    • Creates individual post_stats records for each post
  3. Returns summary counts of the refresh operation

​
Request Body

​
org_group
string
Optional. If provided, only refreshes accounts in this specific org_group
​
force
boolean
Optional. If true, bypasses the once-per-hour rate limit

​
Optional Request Header

​
X-Stream-Progress
'true'
Optional. When set to true, the endpoint streams newline-delimited JSON events with type: "start", type: "progress", and type: "done".

​
Response

​
data
RefreshStatsResponse
Response object containing refresh results summary
# Refresh all accounts in organization
curl -X POST https://api.ugc.inc/stats/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

# Refresh only accounts in a specific org_group
curl -X POST https://api.ugc.inc/stats/refresh \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_group": "influencers"
  }'

{
  "ok": true,
  "code": 200,
  "message": "Stats refresh completed",
  "data": {
    "accounts_refreshed": 3,
    "accounts_failed": 0,
    "total_accounts": 3,
    "post_stats_count": 47
  }
}