---
title: "Start a sound lookup job (TikTok or Instagram)"
method: GET
path: "/v1/satellite/sounds/{platform}/{music_id}"
tags: ["Satellite"]
---

# Start a sound lookup job (TikTok or Instagram)

`GET /v1/satellite/sounds/{platform}/{music_id}`

## Request

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

Queues a deep-dive lookup for every video/reel using the given sound. Supported platforms: `tiktok` and `instagram`. (YouTube is not supported — there is no public "videos using this sound" feed for YouTube.) Returns a job_id immediately. Poll GET /v1/satellite/sounds/status/:job_id for results. The completed result includes the full normalized video list, aggregated stats, and (when trend_analysis=true) an LLM-derived trends block. Each completed job is also persisted as a durable satellite_run that can be re-read for free indefinitely via /v1/satellite/runs/:run_id. Pricing: $0.50 base + $0.50 surcharge when trend_analysis=true. Refunds: a lookup that fails is refunded in full, and the trend_analysis surcharge is refunded when no trends come out (fewer than 10 videos, or the analysis step failed). The amount is reported as credits_refunded.

## Path parameters

- `platform` 'tiktok' | 'instagram', required
- `music_id` string, required

## Query parameters

- `trend_analysis` boolean
- `max_videos` number

## 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 the music_id is not a usable TikTok/Instagram sound id (e.g. a YouTube sound id, or a Virlo UUID for an unsupported platform). Rejected before billing — no credits are charged.
- `401`: Unauthorized - missing or invalid API key
- `402`: Insufficient credits
- `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)