Agent Playbook

The reference docs tell you how to call the API. This page tells you how to think with it — which workflow answers which question, how to get the most on-topic data per dollar, and how to turn responses into correct conclusions. It applies to any subject: Virlo covers every niche, industry, and topic on short-form social.

Route the intent

Pick the workflow by what the user actually wants. Don't run more than you need; don't run less.

Compose them: Orbit surfaces outlier creators → Satellite deep-dives the interesting ones → Tracking monitors the winners. That escalation path (search → inspect → monitor) answers most research tasks end to end.

Async expectations

Full semantics live on the Async Data Model page. The operational summary:

• finalized: true is the only "truly done" signal. status: completed with finalized: false means secondary AI jobs are still running — null analysis or intelligence fields mean "not yet", not "no data".
• partial_failure is a usable terminal state (~7% of runs): one platform or keyword failed, the rest of the data is there. Treat it like completed. Only failed (under 1%) means no data.
• Honor pending_jobs[].retry_after_seconds as your poll interval, or subscribe to webhooks instead.

Realistic production timings — set user expectations with these, not optimistic guesses:

Maximizing data yield

Keywords are the #1 quality lever. Use specific multi-word phrases ("jeep wrangler mods", "high protein meal prep"), never generic single words. Send 3–7 keywords per Orbit covering synonyms and adjacent phrasings of the same concept — each keyword is a separate platform search, so variety widens the net without widening the topic.

• exclude_keywords removes noise; exclude_keywords_strict: true also matches transcripts.
• intent: a one-sentence description of what the user is really after. With intelligence enabled, it powers intent_match=true filtering — the strongest on-topic filter available.
• time_period: this_month is the best default. today/this_week can be thin in narrow niches; this_year dilutes recency.
• min_views: leave unset or low at creation. Filter at retrieval instead — the videos endpoint accepts min_views, platforms, date ranges, and order_by for free, so over-filtering at creation throws away data you paid for.
• enable_meta_ads: true whenever there's any commercial angle.
• data_intelligence_enabled: true (+$1.00) whenever the task involves understanding content (hooks, formats, messaging) rather than just counting views. It cannot be added retroactively.

A typical completed Orbit links ~40–110 videos (broad niches reach 300+), plus slideshows, ads, outlier creators, sounds, an AI analysis, and trend themes. Pull every free sub-resource — most integrations under-read what they already paid for.

For Satellite: raise max_videos to 50–100 (default is only 20), add cross_links=true for other-platform discovery, and save the run_id — GET /v1/satellite/runs/:run_id re-reads any past result free, forever. Check GET /v1/satellite/runs before buying a lookup you may already have.

Spotting the most viral

Raw views mislead — 500K views from a 10M-follower account is routine; the same views from a 3K-follower account is a signal. Virlo's canonical ranking is the weighted virality score:

ratio = views / followers              (only when followers > 0 and ratio > 1)
weighted_score = ln(ratio) × ln(followers)

The procedure:

1. Pull all videos, compute weighted_score from views and author.followers, rank by it.
2. Sanity-check the raw multiplier: views/followers ≥ 20× is notable, ≥ 100× exceptional, ≥ 1000× a mega-outlier.
3. Compute engagement_rate = (likes + comments + shares) / views. High views with engagement above 5% = resonance; below 1% = passive distribution (sounds, reposts, paid).
4. Cross-check the AI's pick: analysis_data.top_10_breakdown is LLM-curated and also weighs quality and topicality. Where your math ranking and the AI ranking agree, you've found the real winners.
5. Creator outliers (/creators/outliers) apply the same logic at account level: sort by weighted_score (= ln(outlier_ratio) × ln(follower_count)), not raw ratio. Best source for rising talent and partnership leads.
6. Check publish_date — a high score this week is a live trend; the same score from months ago is history.

Platform benchmarks

Sampled from production. Never compare raw view counts across platforms.

A 100K-view Reel is a bigger deal than a 100K-view TikTok. Speech-based insights (hooks from transcripts, spoken messaging) come mostly from TikTok; for Instagram lean on descriptions, hashtags, and the AI visual analysis.

Reading intelligence fields

The Video Intelligence page documents every field and enum. How to actually use them:

• Hook analysis is the highest-value group. hook_text is the literal opening copy; hook_type is a closed enum. To answer "what hooks work here": group the top-weighted-score videos by hook_type, then quote real hook_text strings as replicable templates.
• summary exists on every analyzed item. Reading 100 summaries is the fastest way to "watch" 100 videos.
• content_format is an open vocabulary with a canonical core (explainer, tutorial, review, storytime, listicle, …) plus a free-text tail. Match loosely/normalized — treat skit, comedy_skit, and skit_sketch as one bucket.
• Commercial signals — is_sponsored, brands_mentioned[], cta_usages[], social_proof_used[] — are competitive intelligence: who's being paid, which brands appear organically, which CTAs the niche actually uses.
• Trust rules: check intelligence_status === "ready" per item (~94% of videos analyze successfully); discount any field listed in low_confidence_fields[]; transcript_word_count: 0 with populated visual fields means deliberate silent content, not missing data.

The aggregation pattern: the strongest insight format is distribution-over-winners. Take the top quartile by weighted score, count hook_type × content_format × emotional_tone buckets, then contrast against the bottom quartile. The differences are the niche's actual playbook.

Slideshows

TikTok image carousels are a separate result surface (/slideshows) with their own intelligence — in product, education, and lifestyle niches they regularly outperform video.

• panel_texts[] / panel_text_full — the extracted text of every slide, in order. This is the entire content of most slideshows: read it like a script; it's directly replicable copy.
• narrative_arc — how slides progress (the slideshow equivalent of content structure). text_density — text- vs image-dominant.
• Hook = slide 1: analyze hook_text exactly like videos.
• Video-only fields (visual_format, camera_perspective, captions, transcript) don't exist on slideshows — structural, not missing.

Reading AI analysis & trends

GET …/analysis/latest returns analysis_data — a pre-computed research report:

• key_highlight — the single most important finding. overview — executive summary.
• themes[] — clusters of what works, each with why_it_works, tactics[], confidence (0–1: weight ≥ 0.7 heavily, present below 0.5 as tentative), and evidence_video_ids[]. Always join evidence ids back to the video list so claims stay grounded in retrievable examples.
• top_10_breakdown — AI-curated standout videos with reasoning.
• timing_analysis — posting-time patterns. excluded_videos — what the AI judged off-topic (a quick gauge of result purity). connecting_thread — the meta-pattern across themes.

GET …/trends/latest items carry a lifecycle status: new (just emerged — highest opportunity), rising (act now), steady, fading (avoid). On Comets, stable_key follows one trend across cycles — a trend going new → rising with growing video_count is the strongest "post about this now" signal. prev_* fields give cycle-over-cycle deltas.

Audience trust rules

Audience snapshots derive from engaged commenters, not follower counts. Before presenting numbers:

• confidence_level: high/medium → usable; low → say "limited signal", don't state percentages as fact.
• data_source: comments (strongest) → comments_extended → mixed → followers (TikTok-only, capped at medium) → profile_only (no real audience signal found; auto-refunded; treat as "no data available").
• Snapshots are cached free for 30 days (freshness_days); only cache misses cost $0.50.

Spend discipline

• Creation costs money; reading is free. Exhaust the free sub-resources of resources you already created before creating new ones.
• Check the existing lists first (GET /v1/orbit, /v1/comet, /v1/satellite/runs, /v1/tracking/creators) — the answer may already exist in your team's history.
• One well-scoped Orbit beats three vague ones. Spend effort on keyword craft, not retries.
• Quote costs before multi-step plans, check GET /v1/account/balance (free) at session start, and warn the user when X-Balance-Remaining drops below $10.
• Vetting a list of creators? Use POST /v1/satellite/creators/batch (up to 25 at $0.50 each) instead of serial lookups.