Trigger or refresh an audience snapshot for a tracked creator
Cache-first. If a cached snapshot exists within freshness_days, it is returned synchronously and no credits are charged. Otherwise, an async job is enqueued and credits are reserved at the platform-specific rate (audience_snapshot_tiktok / youtube / instagram). If a snapshot job for this creator is already running, its job_id is returned and nothing is charged (credits_used: 0). Audience inference is currently in private preview — generation may take 60-120 seconds. Returns 409 Conflict when the creator's most recent tracking cycle failed or has not yet completed (audience reuses the same upstream provider and would be guaranteed to fail). Pass { "force": true } to bypass this guard for transient platform-side failures.
Request
- Base URL: https://api.virlo.ai
- URL: https://api.virlo.ai/v1/tracking/creators/{id}/audience-refresh
- Auth: HTTP bearer
Path parameters
UUID of the tracked creator
Response
Refresh requested
Example response
{
"data": {
"source": "fresh",
"snapshot": {
"snapshot_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"snapshot_at": "2026-05-21T01:06:00.000Z",
"sample_size": 1500,
"age_distribution": {
"13-17": 0.05,
"18-24": 0.4,
"25-34": 0.35,
"35-44": 0.15,
"45+": 0.05
},
"gender_distribution": {
"female": 0.62,
"male": 0.34,
"unknown": 0.04
},
"country_distribution": [
{
"code": "US",
"name": "United States",
"pct": 0.42,
"confidence": 0.72
}
],
"city_distribution": [
{
"code": "US",
"name": "United States",
"pct": 0.42,
"confidence": 0.72
}
],
"language_distribution": {
"en": 0.78,
"es": 0.12,
"pt": 0.05
},
"confidence_per_signal": {
"age": 0.72,
"gender": 0.78,
"country": 0.65,
"city": 0.55,
"language": 0.7
},
"confidence_level": "medium",
"data_source": "comments",
"signal_breakdown": {
"comments": 245,
"followers": 0
},
"model_version": "v1"
},
"job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "processing",
"credits_used": 50,
"creator_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"credit_unit": "cent",
"pending_jobs": [
{
"type": "viral_analysis",
"status": "processing",
"job_id": "aud_01HXYZ",
"poll_url": "/v1/orbit/orb_01HXYZ/analysis/latest",
"result_path": "data.analysis_data",
"webhook_event": "orbit.run.completed",
"started_at": "2026-05-22T05:00:00.000Z",
"retry_after_seconds": 15
}
]
}
}Changes
No recorded changes to this operation across all 1 revision of this API.