Audience

Poll an audience snapshot job by ID

Returns the current state of a single audience snapshot job. Free — no credit cost. Surfaced as the poll_url on pending_jobs[] entries returned by Satellite and Tracking. Job state is cached in Redis for 24 hours after completion; older job IDs return 404.

get/v1/audience/snapshot/{job_id}

Request

Base URL: https://api.virlo.ai
URL: https://api.virlo.ai/v1/audience/snapshot/{job_id}
Auth: HTTP bearer

Path parameters

job_idstring required

The audience job ID, as returned in pending_jobs[].job_id or in the audience_demographics / audience_geography processing pointer on a Satellite lookup result.

Response

Job state retrieved

Example response

{
  "data": {
    "job_id": "aud_a1b2c3d4e5f6",
    "status": "completed",
    "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"
    },
    "error": {
      "code": "INSUFFICIENT_SAMPLE",
      "message": "Only 12 unique commenters collected (min 30). Creator likely has very little public engagement. The customer was NOT charged for this attempt."
    },
    "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.