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.
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 aggregated results with success/error information for each account

​
Request Body

​
org_group
string
Optional. If provided, only refreshes accounts in this specific org_group

​
Response

​
data
RefreshStatsResponse
Response object containing refresh results for all accounts
# 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,
    "account_stats": [
      {
        "id": "stat_xyz789",
        "account_id": "acc_123456",
        "followers": 15680,
        "following": 345,
        "views": 1285000,
        "likes": 91200,
        "comments": 12500,
        "shares": 8900,
        "saves": 0,
        "created_at": "2024-12-26T15:30:00Z"
      },
      {
        "id": "stat_abc123",
        "account_id": "acc_789012",
        "followers": 28900,
        "following": 500,
        "views": 2100000,
        "likes": 156000,
        "comments": 18700,
        "shares": 12400,
        "saves": 0,
        "created_at": "2024-12-26T15:30:00Z"
      },
      {
        "id": "stat_def456",
        "account_id": "acc_345678",
        "followers": 9200,
        "following": 200,
        "views": 480000,
        "likes": 34500,
        "comments": 5600,
        "shares": 3200,
        "saves": 0,
        "created_at": "2024-12-26T15:30:00Z"
      }
    ],
    "post_stats": [
      {
        "id": "pstat_001",
        "post_id": "post_123",
        "views": 45000,
        "likes": 3200,
        "comments": 450,
        "shares": 280,
        "saves": 0,
        "created_at": "2024-12-26T15:30:00Z"
      },
      {
        "id": "pstat_002",
        "post_id": "post_124",
        "views": 82000,
        "likes": 6100,
        "comments": 890,
        "shares": 520,
        "saves": 0,
        "created_at": "2024-12-26T15:30:00Z"
      }
    ],
    "post_stats_count": 47
  }
}