--- title: "Poll sound lookup status" method: GET path: "/v1/satellite/sounds/status/{job_id}" tags: ["Satellite"] --- # Poll sound lookup status `GET /v1/satellite/sounds/status/{job_id}` ## Request - Base URL: `https://api.virlo.ai` - URL: `https://api.virlo.ai/v1/satellite/sounds/status/{job_id}` - Auth: HTTP bearer Returns the current status of a sound lookup job. Poll until `finalized` is true (status "completed" or "failed"). Results expire after 24 hours, but are also persisted as a durable satellite run — once status reaches "completed" you can re-read the result for free via GET /v1/satellite/runs/:run_id (the run_id is echoed inside the completed result envelope). ## Path parameters - `job_id` string, required ## Response `200` Job status retrieved. Shape varies by status: processing, completed (with full result), or failed (with error). - SoundStatusResponseDto - `data` union, required - SoundStatusProcessingDto - `status` 'processing', required - `finalized` boolean, required: Always false while the lookup is still running. - SoundStatusCompletedDto - `status` 'completed', required - `result` SoundLookupResultDto, required - `run_id` string, uuid, required: Durable satellite_run id for this lookup. Use it with GET /v1/satellite/runs/:run_id to re-read the result for free at any time. - `request` SoundLookupRequestDto, required - `music_id` string, required - `platform` 'tiktok' | 'instagram', required - `trend_analysis` boolean, required - `max_videos` number, required - `sound` SoundMetadataDto, required - `music_id` string, required - `platform` 'tiktok' | 'instagram', required - `title` string, nullable - `is_original` boolean, required - `is_commerce_music` boolean, required - `duration_seconds` number, nullable - `cover_url` string, nullable - `owner` object, required - `reported_usage_count` number, nullable: Platform's reported usage count for the sound, independent of our sample (TikTok `user_count`). Null for Instagram — the IG audio feed exposes no authoritative total-usage count. - `data_captured_at` string, date-time, required - `credits_charged` number, required: Credits actually charged for this lookup. 50 for a basic lookup, 100 when trend_analysis=true (50 base + 50 surcharge). - `credits_refunded` number: Credits paid back because part of the run was not delivered (the trend_analysis surcharge when no trends came out). Present only when a refund was made. - `stats` SoundStatsDto, required - `videos_analyzed` number, required - `views` SoundStatsViewsDto, required - `total` number, required - `avg` number, required - `median` number, required - `max` number, required - `min` number, required - `engagement` SoundStatsEngagementDto, required - `total_likes` number, required - `total_comments` number, required - `total_shares` number, required - `total_collects` number, required - `avg_likes` number, required - `avg_comments` number, required - `avg_shares` number, required - `avg_collects` number, required - `engagement_rate` number, required - `velocity` SoundStatsVelocityDto, required - `videos_per_week` SoundStatsVelocityBucketDto[], required - … - `last_4w_avg_videos_per_week` number, required - `prior_4w_avg_videos_per_week` number, required - `is_accelerating` boolean, required: True when last_4w_avg ≥ prior_4w_avg * 1.15. - `verified_creator_count` number, required - `verified_creator_pct` number, required - `commerce_music_pct` number, required - `duration_distribution` SoundStatsDurationDistributionDto, required - `under_15s` number, required - `between_15_30s` number, required - `between_30_60s` number, required - `over_60s` number, required - `top_creators` SoundStatsCreatorDto[], required - `unique_id` string, required - `nickname` string, nullable - `is_verified` boolean, required - `follower_count` number, nullable - `video_count` number, required - `total_views` number, required - `avg_views` number, required - `top_hashtags` SoundStatsHashtagDto[], required - `hashtag` string, required - `used_count` number, required - `total_views` number, required - `avg_views` number, required - `top_video` SoundCustomerVideoDto - `id` string, required - `url` string, required - `description` string, required - `publish_date` string, date-time, nullable - `duration_seconds` number, nullable - `views` number, required - `likes` number, required - `comments` number, required - `shares` number, required - `collects` number, required - `hashtags` string[], required - `is_duet` boolean, required - `is_stitch` boolean, required - `region` string, nullable - `author` SoundCustomerVideoAuthorDto, required - … - `sample_quality` SoundSampleQualityDto, required - `truncated_by_cap` boolean, required - `pages_fetched` number, required - `note` 'insufficient_corpus' | 'small_corpus_workable' | 'healthy_corpus' | 'deep_corpus', required - `trends` SoundTrendsDto, required - `analyzed` boolean, required: True iff trend_analysis was set on the request. - `summary` string, required - `trends` SoundTrendItemDto[], required - `name` string, required - `description` string, required - `tactics` string[], required - `confidence` number, required - `video_count` number, required - `evidence_video_ids` string[], required - `time_windows` SoundTrendsTimeWindowDto[], required - … - `resurged` boolean, required: True iff this trend has ≥2 time_windows. - `momentum` 'stronger' | 'weaker' | 'similar', nullable: Latest vs prior window avg_views. Null for single-window trends. ±15% deadband. - `model_used` string, nullable - `cost_usd` number, nullable - `tokens_used` number, nullable - `status` 'ok' | 'insufficient_corpus' | 'skipped', required - `videos` SoundCustomerVideoDto[], required - `id` string, required - `url` string, required - `description` string, required - `publish_date` string, date-time, nullable - `duration_seconds` number, nullable - `views` number, required - `likes` number, required - `comments` number, required - `shares` number, required - `collects` number, required - `hashtags` string[], required - `is_duet` boolean, required - `is_stitch` boolean, required - `region` string, nullable - `author` SoundCustomerVideoAuthorDto, required - `unique_id` string, nullable - `nickname` string, nullable - `is_verified` boolean, required - `follower_count` number, nullable - `finalized` boolean, required: Always true once the lookup completed: trends and any refund are settled before it reads completed. Same done signal as the other async status replies. - SoundStatusFailedDto - `status` 'failed', required - `error` string, required - `credits_refunded` number: Credits paid back because the lookup failed. Present only when a refund was made. - `finalized` boolean, required: Always true when the lookup failed: no further work will happen. ## Other responses - `401`: Unauthorized - missing or invalid API key - `404`: Job not found or expired - `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)