---
title: "Start a creator lookup job"
method: GET
path: "/v1/satellite/creator/{platform}/{username}"
tags: ["Satellite"]
---

# Start a creator lookup job

`GET /v1/satellite/creator/{platform}/{username}`

## Request

- Base URL: `https://api.virlo.ai`
- URL: `https://api.virlo.ai/v1/satellite/creator/{platform}/{username}`
- Auth: HTTP bearer

Queues a creator lookup for processing. Returns immediately with a job_id. Poll GET /v1/satellite/creator/status/:job_id for results. Pricing: $0.50 base. Optional surcharges — trend_analysis=true (+$0.50); data_intelligence=true (+$0.25) enriches each video with structured content intelligence and a grounded "what's working" analysis, retrievable on GET /v1/satellite/runs/:run_id once intelligence_status is "ready"; audience_demographics / audience_geography (+$0.50 for a fresh snapshot — the two flags share one snapshot and are never double-charged; a cached snapshot within freshness_days is free). Ceiling with every add-on: up to $1.75. Refunds: a lookup that fails (for example a handle with no public posts, or a run that stalls and is failed by the recovery sweep) is refunded in full, and a surcharge whose add-on produced nothing is refunded (trend_analysis that yields no trends, an audience snapshot that was already cached or already being built, data_intelligence on a creator with no posts to enrich or whose analysis failed). The amount is reported as credits_refunded on the completed result or the failed status, and on GET /v1/satellite/runs/:run_id. Cache: a repeat lookup of the same creator within 6 hours returns the earlier run free (cached: true, status "completed"), but only when that run covers every option this request asks for: each add-on and include flag it turns on, at least as many max_videos, and the same outlier_threshold. Anything else, such as trend_analysis=true after a plain lookup, runs fresh and is charged.

## Path parameters

- `platform` 'youtube' | 'tiktok' | 'instagram', required
- `username` string, required

## Query parameters

- `include` string
- `cross_links` boolean
- `max_videos` number
- `outlier_threshold` number
- `audience_demographics` boolean
- `audience_geography` boolean
- `freshness_days` number
- `trend_analysis` boolean
- `data_intelligence` boolean
- `context` string
- `slideshow_sort` 'recent' | 'popular'

## Response `200`

Job queued successfully

- SatelliteJobQueuedResponseDto
  - `data` SatelliteJobQueuedDataDto, required
    - `job_id` string, required
    - `status` string, required: Usually "processing". On a cache hit (same lookup repeated within the 6-hour window, answered by a run that covers every option asked for) the job is already done and this is "completed" — poll the status endpoint once to read the result, or re-read it free via GET /v1/satellite/runs/:run_id.
    - `cached` boolean: Present and true when the lookup was served from the 6-hour cache. The cache only answers with a run that covers every option this request asks for; a request it does not cover (for example trend_analysis=true after a plain lookup) runs fresh and is charged. Cached responses are free — no credits are deducted (X-Credits-Used: 0).

## Other responses

- `400`: Invalid platform or username
- `401`: Unauthorized - missing or invalid API key
- `429`: Too many requests - rate limit exceeded

---

[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)