Tracking

Start tracking a creator

Begin monitoring a creator's metrics over time. Each recurring cycle collects fresh metrics and generates an AI report (charged per cycle).

post/v1/tracking/creators

Request

  • Base URL: https://api.virlo.ai
  • URL: https://api.virlo.ai/v1/tracking/creators
  • Auth: HTTP bearer

Request body

urlstring

Creator profile URL

handlestring

Creator handle (requires platform)

platform'tiktok' | 'youtube' | 'instagram' required

Platform the account or video is on.

scrape_cadence'six_hours' | 'twelve_hours' | 'daily' | 'every_other_day' | 'weekly' | 'bi_weekly' | 'monthly'

How often to collect metrics and generate an AI report (default: daily)

collection_depth'standard' | 'deep' | 'full'

Optional initial post collection depth. When set, an initial deep post-collection runs alongside the first cycle to back-fill a deeper post history (and per-post sound) than the daily shallow sample: standard (up to 50 videos, +50 credits/$0.50), deep (up to 200, +100/$1.00), full (up to 500, +200/$2.00). The depth cost is charged once at this request on top of the $0.25 cycle (see the X-Cost / X-Credits-Used headers). If omitted, only daily shallow collection runs.

Example request

{
  "url": "https://www.tiktok.com/@creator",
  "handle": "creator_handle",
  "platform": "tiktok",
  "scrape_cadence": "daily"
}

Response

Creator tracking enqueued

Example response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "active",
    "message": "Creator tracking started. Initial metrics and AI report are being generated.",
    "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.