What's new on the Virlo API. New endpoints, pricing changes, performance work, deprecations, and fixes — newest first.
Recurring Content Research Agents now stay aware of what is happening in their topic. When an agent detects a breaking event in its niche — a death, record, launch, or controversy the space is suddenly talking about — via a burst in its own collected videos or a news scan, it surfaces the story and adds short-lived timely keywords to chase it. Read the detected events any time with the new free GET /v1/agents/:id/events: each event carries a title, summary, salience (0–10), lifecycle status (candidate / confirmed / dismissed / expired), the timely keywords, and evidence videos ([{ url, views, description }]), active events first. Subscribe to the new content_research_agent.event.detected webhook to get pushed the moment an event is confirmed — it fires between scheduled runs and carries the event plus what the agent did about it (action_taken: timely_keywords / collecting_early / breaking_ingest / none). MCP clients get a new get_niche_monitor_events tool. Everything is additive — existing agents, endpoints, and webhook payloads are unchanged, and one-shot agents are unaffected. See /docs/agents and /docs/webhooks.
Satellite gains a third lookup type: hashtags. GET /v1/satellite/hashtags/:platform/:hashtag (50 credits / $0.50) queues an async lookup of what is being posted under a tag on tiktok (native challenge feed), instagram (Google-indexed public Reels — best-effort coverage), or youtube (native hashtag page, Shorts only); poll GET /v1/satellite/hashtags/status/:job_id for free. Completed results carry the collected video corpus (max_videos 1–100, default 50; sort=top by views or recent by publish date) plus aggregate stats: view and engagement aggregates, posting velocity with an is_accelerating signal, duration_distribution, top_creators (10), related_hashtags (20 co-occurring tags), top_sounds (10), and a sample_quality corpus-health note. A depth query param scales the corpus: standard (default, the max_videos behavior), deep (~300 videos, +50 credits / $0.50 — $1.00 total; surcharge waived when combined with trend_analysis=true), or full (~500 videos, +150 credits / $1.50 — $2.00 total, $2.50 with trends) — TikTok and YouTube only; Instagram supports standard only and deeper tiers return 400 before billing. Add trend_analysis=true (+50 credits / $0.50 — $1.00 total) for LLM-detected content trends over a ~300-video deep fetch, identical in shape to sound-lookup trends. Repeating the same lookup within 6 hours returns the cached run free, and every lookup persists as a durable satellite run (type=hashtag_lookup) — re-read free forever via GET /v1/satellite/runs/:run_id. The satellite.lookup.completed webhook fires with data.type = "hashtag_lookup", and MCP clients get a new lookup_hashtag tool (49 tools total). See /docs/satellite.
GET /v1/trends/emerging now costs **$0.25** (25 credits) per call, the same as GET /v1/trends and GET /v1/trends/digest. It shipped as a free read on 2026-07-07 and became billable on 2026-07-30; several docs surfaces continued to describe it as free until 2026-08-02, and those have now been corrected. Per-plan rate limiting is unchanged, and GET /v1/trends/regions remains free. As always, the authoritative cost of any call is the X-Cost / X-Credits-Used response header. See /docs/credits.
Trends now carry a live momentum signal, and there is a new endpoint for what is heating up right now. Every trend on GET /v1/trends and GET /v1/trends/digest gains an additive momentum object (status — new / rising / steady / fading, a 0–1 score, views_per_hour, and updated_at). Momentum is refreshed by a background loop roughly every 2 hours (configurable per region) that re-reads only exemplar view/like counts — no re-clustering. The new GET /v1/trends/emerging returns a flat, momentum-ranked list of early-stage (new/rising) trends for a region, composable with region (e.g. region=gb for "what's emerging in the UK right now"). It reads maintained state so it responds fast, is a free read, and is rate-limited per plan for user-triggered in-product use. All fields are additive; existing integrations are unaffected. See /docs/trends.
Trends now support regions. GET /v1/trends and GET /v1/trends/digest accept an optional region query param — us, gb, or au for country-specific trends detected from that region's own curated sources, refreshed three times per day in the region's local timezone. Omitting region (or passing global) returns the worldwide feed, preserving the exact historical behavior — existing integrations are unaffected. The new free endpoint GET /v1/trends/regions lists available codes; more regions (including sub-regions like major city hubs) will be added over time, so discover codes at runtime instead of hard-coding. Responses gain additive fields: region and local_date on each trend group, plus detected_at, last_seen_at, origin_region_codes, and global_confidence on each trend — the latter two identify trends independently detected in multiple countries and promoted into the global feed. See /docs/trends.
Creating a recurring agent (POST /v1/agents with is_recurring: true) now accepts the "daily", "weekly", and "monthly" cadence shortcuts in addition to a raw cron expression — the shortcuts are normalized to their cron equivalents before scheduling, matching what the docs describe. Previously only a full cron expression was accepted and the shortcuts returned a 400 "Invalid cron expression". Cron expressions must still run at most once per day.
Orbit (one-shot search) and Comet (recurring monitoring) are unified into a single /v1/agents resource: POST /v1/agents with is_recurring: false for a one-shot search or is_recurring: true (+ cadence) for a recurring monitor. /v1/agents is a full superset of both legacy surfaces — every read lives at the same sub-path (/videos, /slideshows, /ads, /creators/outliers, /analysis[/latest], /trends[/latest], /hashtags, /benchmarks, /affinity, /creators/:creator_id/similar, /sounds) and legacy orbit_id/comet_id values are interchangeable with agent IDs, so reads work on either surface during migration. New capabilities on top: /runs history, an autonomy surface (/activity decision log, /proposals with apply/dismiss/revert, PUT /:id/autonomy for suggest vs autopilot), and a unified content_research_agent.run.completed webhook. Collection scope is system-managed (no min_views/time_range at creation) — filter by views/date/platform for free at read time on /videos. Discovery reads (hashtags, benchmarks, affinity, similar creators, trending sounds) now work for one-shot agents too, not just recurring monitors.
The /v1/orbit and /v1/comet endpoint families are deprecated in favor of the unified /v1/agents resource and will be removed on **August 3, 2026**. Until then they keep working unchanged, and because IDs are interchangeable, migration is a same-path rename (/v1/orbit/:id/videos → /v1/agents/:id/videos, etc.). Create-time min_views / time_range / time_period are accepted but ignored (collection is system-managed); move filtering to read-time query params. Legacy orbit.run.completed / comet.run.completed webhook events keep firing until removal — subscribe to content_research_agent.run.completed going forward. See the migration guide at /docs/agents.
Comet niche monitors gain a suite of free TikTok-genre discovery reads. GET /v1/comet/:id/hashtags returns per-hashtag analytics (volume, total/avg views, avg engagement, run-over-run growth + lifecycle, and top creators per tag; sort=volume|growth|avg_views). GET /v1/comet/:id/benchmarks returns genre norms (median engagement rate, followers, niche video count, and posting frequency) bucketed by follower tier (nano/micro/mid/macro). GET /v1/comet/:id/affinity (exploratory) returns genre adjacency — dominant creator topics plus co-occurring hashtags and sounds. GET /v1/comet/:id/creators/:creator_id/similar (exploratory) ranks niche creators by shared hashtags and sounds with a target creator. All are free reads, consistent with existing Comet sub-resources.
GET /v1/comet/:id/sounds now accepts sort=rising / growth_7d to rank sounds by run-over-run growth in niche usage (the "what sound is breaking out in this genre right now" signal); every row additionally carries growth_video_count, growth_views, and a new/rising/steady/fading lifecycle label. GET /v1/comet/:id/creators/outliers now accepts order_by=rising (true run-over-run velocity from per-run snapshots, transparently falling back to the weighted-outlier ranking on a young monitor) plus follower_tier (nano/micro/mid/macro) and category (topic substring) filters. Comet keywords now normalize hashtag-style tokens — #progressivehouse and progressive house resolve to the same keyword. All additive; existing calls are unchanged.
GET /v1/sounds/:sound_id now always returns a track_resolution object that maps a sound to its canonical recording — status (unresolved | pending | resolved | not_found), artist_name, isrc, spotify_track_id, spotify_artist_id, release_status, resolution_source, release_date, confidence, and resolved_at. Resolution is lazy: pass resolve=true to trigger an on-demand Spotify track match. A fresh resolution adds the sound_artist_resolution feature cost ($0.10); re-reads of an already-resolved sound stay free even with resolve=true.
GET /v1/sounds/trending now defaults to sort=videos_7d — sounds ranked by # videos published using each sound in the last 7 days, the recency-weighted "what is rising right now" signal. videos_30d is also available. The legacy sorts usage_count and video_count (all-time greatest hits) remain available for callers asking reach-not-momentum questions. Velocity sorts include a new videos_in_window field on each item, and the response echoes the sort mode at the top level.
New GET /v1/sounds/breakout ($0.25) surfaces sounds with the highest recent-burst ratio — rapidly rising from a small baseline. Distinct from /v1/sounds/trending: trending favours large absolute weekly volume (mature sounds still gaining lots of videos), while breakout favours sounds where almost all activity happened in the last 7 days. Score = videos_7d × (videos_7d / videos_90d). Each item carries videos_7d, videos_30d, videos_90d, burst_ratio, and breakout_score. Tunable via min_recent / min_baseline to control the noise floor.
Sound responses now expose the artist name on owner_nickname for music-label tracks (Espresso, Anti-Hero, Laxed, etc.) where TikTok does not assign an individual creator handle. Previously these fields were null because our normalizer only read TikTok's owner_handle/owner_nickname fields, which are empty for licensed music. We now also read the artist from matched_song.author (preferred) or author, populating owner_nickname for ~46K previously-unattributed TikTok sounds going forward, and via a one-time backfill for existing sounds.
Orbit and Comet requests with data_intelligence_enabled=true now charge 150 credits ($1.50) instead of 50 credits ($0.50) to reflect the additional AI analysis cost.
Reduced unnecessary top-up checks during high-volume bursts. Auto top-ups now fire at most every 5 minutes per account.
Optional AI analysis layer that surfaces topics, sentiment, demographic fit, and viral potential alongside Orbit and Comet results.
Audio intelligence is now first-class. New endpoints: GET /v1/sounds/trending, /v1/sounds/search, /v1/sounds/{id}, /v1/sounds/{id}/videos, /v1/sounds/usage-history, /v1/sounds/by-creator/{creator_id}. Sound metadata is also enriched into Orbit, Comet, Satellite, and Tracking video responses.
Subscribe to events with POST /v1/webhooks (also GET, PATCH, DELETE). Supports tracking cycle completion, outlier detection, paused events, creator post collection, and posting cadence analysis. Real-time integrations no longer need polling.
Analysis and trends endpoints have been normalized so that all sub-resources sit under /:entity/:id/:sub. The previous routes still resolve but new integrations should use the consistent shape.
Tracking and Comet responses now strictly enforce a public field allowlist; internal scoring/debug fields have been removed.
New endpoints: GET /v1/comet/{id}/trends, /v1/comet/{id}/trends/history, /v1/comet/{id}/analysis, /v1/comet/{id}/analysis/history (and the matching /v1/orbit/{id}/... set). Detail responses now expose analysis_data, analysis_batch_start, and analysis_batch_end.
Tracking event webhooks can now post directly to Slack with no glue code.
Orbit and Comet now return TikTok slideshows (multi-image carousels) alongside individual videos, with an is_slideshow flag for filtering.
Poll long-running batch creator lookups with GET /v1/satellite/creators/batch/{batch_id}.
Per-platform view counters were collapsed into one cross-platform total_views field for cleaner analytics.
New endpoints: POST/GET /v1/tracking/creators/{id}/posts (standard / deep / full collection tiers), /v1/tracking/creators/{id}/posting-cadence, and POST/GET /v1/satellite/creators/batch for bulk lookups with AI category tagging. Video responses now include is_duet and is_stitch.
New optional weighted_score field returned by Satellite, Orbit, and Comet responses. Combines engagement, growth, and audience size into a single ranking signal. Available as a sortBy value on outlier endpoints. (Renamed from "Virlo Score" prior to launch.)
Credit deduction is now method-aware — GET requests against credit-free endpoints are no longer charged.
Tracking and Comet now accept bi_weekly (14-day) and monthly (30-day) scrape cadences alongside the existing daily and weekly options.
Tracking responses now include delta_* fields showing change from the previous snapshot, and Tracking list endpoints accept a search query parameter for filtering by handle or title.
Check remaining credits programmatically with GET /v1/account/balance.
Replaced a full-table-scan RPC with a materialized view. Median hashtag stats latency dropped from ~6s to ~59ms.
Every billable response now includes X-Cost and X-Balance-Remaining headers. When credits run out, the API returns 402 Payment Required with a funding link in the error body.
TikTok scrapes now run on Virlo Lambda first with automatic fallback to the previous provider. Roughly 70% lower upstream cost and faster end-to-end response times. Includes pre-warming of the TikTok transcript cache.
New endpoints: POST /v1/tracking/creators and POST /v1/tracking/videos for monitoring creators and videos over time, with snapshot history and outlier detection. Returns 402 Payment Required when account credits are insufficient before starting a job.
AI analysis is now generated automatically on every Tracking cycle, so the standalone POST .../report routes have been retired. Pull analysis from the regular detail endpoint instead.
All /v1 endpoints now publish full Swagger/OpenAPI type definitions, including nullable/array shapes — making MCP and AI-agent auto-generation work cleanly.
YouTube data flows through Virlo Lambda by default with automatic fallback to ScrapeCreators on failure. Eliminates per-request upstream cost and improves reliability.
Legacy unversioned endpoints are now marked deprecated. They continue to work but new integrations should use the /v1 prefix. A removal date will be announced in advance.
The full Swagger/OpenAPI document is now exposed at GET /openapi.json for MCP servers and AI agents to discover the API automatically.
Responses now include an AI-derived intent field that classifies content by user intent (e.g. educate, sell, entertain) so customers can segment results by motivation.
Billable POST requests now trigger an account-level credit top-up check. Reduces the chance of mid-burst 402 errors for accounts with auto-recharge enabled.
Removed the implicit default to make timeframe explicit and avoid surprising aggregate windows. Pass time_period (e.g. 7d, 30d, 90d) on hashtag and video analytics calls.
Per-response credit accounting has moved to the X-Cost response header (added 2026-04-01). The legacy creditsUsed body field has been removed.
Instagram media thumbnails are now cached and rewritten to long-lived URLs, fixing the 24-hour image expiration that was breaking downstream storage.
New endpoint GET /v1/comet/{id}/video-outliers surfaces videos with anomalous engagement or growth within a Comet niche.
Run bulk creator profile lookups asynchronously and poll for results. Useful for ingesting large creator lists without hitting per-request rate limits.
Full rewrite of the video ingestion pipeline with a new queue architecture. Faster processing, better data quality, and dramatically fewer ingestion failures during traffic spikes.
New POST /v1/teams/* endpoints for creating teams, managing members, and inviting collaborators. Credits are now pooled at the team level so multiple API keys can share a single balance.
New endpoint GET /v1/satellite/creators/{handle} returns a single cross-platform profile (TikTok, Instagram, YouTube) with normalized stats, recent posts, and category tags.
Versioned API surface launched with standardized snake_case naming, consistent envelopes, and explicit schemas. New routes: /v1/hashtags, /v1/comet, /v1/orbit, /v1/videos, /v1/trends, plus per-platform /v1/{tiktok,instagram,youtube}/* endpoints.
New endpoints GET /v1/orbit/{id}/creator-outliers and GET /v1/comet/{id}/creator-outliers surface creators with abnormal growth or engagement spikes — useful for catching breakouts and flagging suspicious activity.
New endpoints: GET /hashtags/{id}/performance (per-hashtag time-series) and POST /comet/{id}/ads (Meta/Facebook ad creative discovery scoped to a Comet niche).
New endpoints POST /comet and GET /comet/{id} for analyzing custom creator niches and discovering opportunities. Customers can define their own niche definitions instead of being limited to preset categories — Comet then groups videos by AI-derived theme.
Orbit responses now include AI-generated keyword trend and creator insight summaries, powered by a new analysis service.
Video search responses now echo back the keyword that matched, so downstream pipelines can attribute results without re-tracking the query.
New endpoints POST /orbit/keyword-searches and GET /orbit/keyword-searches for discovering creators producing content around specific keywords across TikTok, Instagram, and YouTube.
Introduced a credit-based pricing model: each endpoint deducts a defined credit cost from the account balance. See the Pricing page for the full table.
Hashtag and video endpoints now accept a platform query param (tiktok, instagram, youtube) to scope results to a single network.
New endpoint GET /niches/{niche_id}/trends for niche-scoped trend discovery.
Public API launched with three core endpoints: GET /hashtags, GET /videos, GET /trends. Covers TikTok and Instagram at launch with YouTube to follow.
Looking for a specific change? Email us.