Tracking

Get inferred audience country + city distributions

Returns the latest cached audience snapshot for the tracked creator, projected onto the geography fields. A single snapshot powers both demographics and geography views; if you previously called audience-demographics, the same snapshot is reused for free.

get/v1/tracking/creators/{id}/audience-geography

Request

Base URL: https://api.virlo.ai
URL: https://api.virlo.ai/v1/tracking/creators/{id}/audience-geography
Auth: HTTP bearer

Path parameters

idstring required

UUID of the tracked creator

Query parameters

freshness_daysnumber

Age in days (0-365) after which the snapshot reports is_stale: true. Omit to skip the staleness check.

Response

Audience geography snapshot

Example response

{
  "data": {
    "platform": "tiktok",
    "handle": "creator_handle",
    "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"
    },
    "finalized": true,
    "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.