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: a one-shot agent 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 agent 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 / min_views: deprecated no-ops at creation — do not send them. Collection scope is system-managed: every search/monitor collects the widest relevant net (cadence-aware date window, no view floor) so nothing is missed. Filter at retrieval instead — the videos endpoint accepts min_views, platforms, start_date/end_date, region, and order_by for free, so you can slice the collected data any way without re-running the job.
• english_only: defaults to true (English-only collection). Set false to research non-English or global niches — and when you do, write keywords and intent in the target language (the keyword engine adapts to your input language). This is the switch that opens the gates to content in other languages; forget it and a Spanish or Thai request quietly returns almost nothing.
• meta_ads_enabled: 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.

Filtering by upload region (beta). When the user asks "show me videos from Canada / Russia / Australia", pass region=<ISO-3166-1 alpha-2> (e.g. US, CA, RU, AU, case-insensitive) to the agent videos and slideshows endpoints — resolve the country name to its code yourself. Each item carries upload_region (videos) / region (slideshows). Region is deterministic where the platform provides it (TikTok video/creator region, YouTube channel country) and AI-inferred otherwise, so coverage is partial and improving — items without a resolved region are simply excluded when you filter. Slideshows have the highest region coverage (straight from TikTok), so a slideshow-heavy niche is the most reliable surface for regional slicing. This pairs naturally with english_only: false for geo-targeted, non-English research.

A typical completed agent run 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.

Recurring-agent autonomy

Recurring agents (is_recurring: true) self-optimize by proposing keyword_refresh and filter_change changes rather than silently drifting.

• Read pending work with GET /v1/agents/:id/proposals (status pending | applied | auto_applied | dismissed | reverted) and the decision log with GET /v1/agents/:id/activity.
• Act with POST /v1/agents/:id/proposals/:pid/{apply,dismiss,revert}.
• The first manual apply unlocks autopilot for the whole team. After that, newly created agents come back at autonomy_level: "autopilot" with autopilot_unlocked: true instead of the initial suggest — this is expected, not a bug.
• Set the mode explicitly with PUT /v1/agents/:id/autonomy { autonomy_level, cognition_enabled }.

One-shot agents expose these fields but never generate proposals or activity — there is no future run to improve. Full reference: Autonomy.

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 recurring agents, 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/agents, /v1/satellite/runs, /v1/tracking/creators) — the answer may already exist in your team's history.
• One well-scoped agent 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 that balance drops below $10 — read it from GET /v1/account/balance, not the X-Balance-Remaining header (which only appears on charged responses).
• Vetting a list of creators? Use POST /v1/satellite/creators/batch (up to 25 at $0.50 each) instead of serial lookups.