---
title: "Start tracking a creator"
method: POST
path: "/v1/tracking/creators"
tags: ["Tracking"]
---

# Start tracking a creator

`POST /v1/tracking/creators`

## Request

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

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

## Request body

- V1TrackCreatorDto
  - `url` string: Creator profile URL
  - `handle` string: 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.

## Response `202`

Creator tracking enqueued

- TrackCreatorResponseDto
  - `data` TrackCreatorResultDto, required
    - `id` string, required
    - `status` string, required
    - `message` string, required
    - `finalized` boolean: Always false at creation time — the first cycle (scrape + AI report) is in-flight. Poll `GET /v1/tracking/creators/:id` and watch `finalized` flip to `true` (or subscribe to `tracking.cycle.completed`).
    - `pending_jobs` PendingJobDto[]: Always contains a single `tracking_report` entry pointing at the in-flight first cycle. Mirrors the same shape every other async resource exposes so a single polling helper handles Track / Refresh / Lookup uniformly.
      - `type` 'viral_analysis' | 'audience_demographics' | 'audience_geography' | 'tracking_report', required: Stable identifier for the kind of secondary job. Use this to switch on the field where the result will appear (see `result_path`).
      - `status` 'pending' | 'processing', required: Current non-terminal state of the job. Once the job reaches a terminal state (ready / failed / skipped) the entry is removed from `pending_jobs[]`.
      - `job_id` string: Optional opaque identifier for the underlying job, when one exists. Useful with `poll_url` to fetch the result directly.
      - `poll_url` string: Path (relative to api.virlo.ai) you can GET to fetch the result of this job once it is ready. Free to call.
      - `result_path` string: Dot-path inside the parent resource's response body where the completed result will appear. Useful for clients that re-fetch the resource instead of using `poll_url`.
      - `webhook_event` string: Name of an event from the existing `SUPPORTED_EVENTS` list that fires when this job reaches a terminal state. Subscribe to it via POST /v1/webhooks to avoid polling. Guaranteed to be one of the already-supported event names so existing webhook subscriptions keep working — no new event types were introduced.
      - `started_at` string: When the job entered its current state (ISO 8601 UTC).
      - `retry_after_seconds` number: Suggested minimum delay (seconds) before polling again. Respect this to avoid hitting rate limits.

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - missing or invalid API key
- `402`: Insufficient credits
- `409`: Already tracked by this account. A creator can be tracked once per account, across the web app and the API; the message says where.
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)