Research playbook

How to pick the right Virlo workflow for a research question, in any niche, and how to read what comes back.

Pick the right workflow

Find your question. Swap :id-style parts for real values.

An agent (Content Research Agent) collects TikTok, YouTube, and Instagram videos for your keywords. Data Intelligence (+$1.00 per run) adds an AI breakdown of the videos worth studying. A creator lookup's $0.25 AI read is separate and covers fewer fields.

Research a niche

Look up or track one thing

Trends, sounds, and hooks

Most research follows one path: a one-time agent finds outlier creators (creators whose views far beat their follower count), a creator lookup checks the best ones, and tracking follows the winners.

How long things take

Agents and lookups run in the background. Start a job, check back at the pace in the table below until it's done (polling), then read the results. Or get a webhook when it finishes. More in How results load.

• Done means finalized: true. status: completed alone can mean the AI report is still being written. Empty (null) AI fields mean "not yet," not "no data." The exception is a video with intelligence_status: "skipped": its intelligence will never arrive.
• partial_failure is usable (about 2% of runs). One platform or keyword failed, and the rest is there. Only failed (rare) means no data.
• Each status reply says when to check next (pending_jobs[].retry_after_seconds).

Trend analysis makes sound and hashtag lookups a little slower. The job status check stops working after 24 hours.

Setting up an agent

Keywords matter most. Use specific phrases of two or more words ("jeep wrangler mods", not "jeep"). Send 7 to 12, the number suggest-keywords returns (50 at most); the price is the same. Cover synonyms of the same idea: each keyword is its own search on each platform.

Write a real intent. One required sentence on what you want to find. With Data Intelligence on, AI checks each video against it, and intent_match=true keeps only the matches when you read videos. See the Intent cookbook.

Exclude words that pull in the wrong topic, like apple the fruit when you mean Apple the company. A few exclude words remove more junk than an extra keyword adds.

• Each is matched as a whole word against captions and hashtags. exclude_keywords_strict also checks what's said in the video.
• Use single words from the other meaning (recipe, fruit, orchard). Phrases like apple the fruit filter out almost nothing, and excluding your own topic (apple) removes everything.
• The free keyword helper (POST /v1/agents/suggest-keywords) returns a ready exclude_keywords list. Pass it straight through.

Other settings:

• Don't send time_period or min_views. POST /v1/agents rejects them with a 400 error (MCP tools ignore them). Filter when you read instead, for free: the videos endpoint takes min_views, platforms, start_date, end_date, region, and order_by.
• english_only is true by default, which now means English-speaking Western markets: creators in the US, UK, Canada, Australia, Ireland and Western and Northern Europe only, excluded elsewhere even when they post in English. For non-English or global niches, set it to false and write the keywords and intent in that language, or you get almost nothing.
• meta_ads_enabled: true also collects matching ads from Meta's ad library at no extra cost, but a run can take up to about 45 minutes. Use it when a brand or product is involved.
• data_intelligence_enabled: true (+$1.00 per run) when you want to understand content (hooks, formats, messaging), not just count views. You can't add it to a run afterward.

Reading what you collected

Read everything you paid for. Reading is free. A one-time run keeps about 360 videos (later recurring runs about 200), plus slideshows, ads, outlier creators, sounds, an AI report, and trends. Once it's finished, start with GET /v1/agents/:id/summary, then read the full lists.

Filter by upload country (beta). Add region with a two-letter code (US, CA, any case) to the agent's videos or slideshows endpoint. A country name returns nothing, so convert it yourself. Coverage is partial: items with no known country drop out.

Creator lookups: add include=videos,outliers and raise max_videos to 50 to 100 (the default is 20; sound and hashtag lookups already default to 50). The price stays $0.50. cross_links=true finds the creator's profiles on other platforms.

All lookups (video outlier checks included) are saved. Re-read one free at GET /v1/satellite/runs/:run_id; the run_id is the job ID. Each paid lookup is saved as a new run with its own run_id, so a later lookup of the same creator, sound, or hashtag never overwrites an earlier one.

Refunds. Virlo refunds a failed creator, sound, or hashtag lookup in full, for example a handle that doesn't exist, or a lookup that stalls and is closed out as failed. The trend analysis surcharge comes back when no trends come out, the audience surcharge when no new snapshot was needed, and the Data Intelligence surcharge when the lookup had no posts to enrich or its analysis failed. The result or failed status then shows credits_refunded, in credits, and so does the saved run at GET /v1/satellite/runs/:run_id, even for a failed lookup. The hashtag depth surcharge comes back only when the whole lookup fails.

How recurring agents improve themselves

After each run, a recurring agent tunes its own keywords so it keeps finding new videos. This is autopilot. It is on by default for every new agent, whether you make it through the API, over MCP, or in the Virlo app.

• What it does: rewords searches, adds keywords (up to 15 in all), adds short-lived keywords for breaking stories in the niche, and collects more widely after a thin run. Keyword changes must pass a quality check first.
• What it never does: remove a keyword or exclude term you set (returned as pinned_keywords), add charges, change the schedule, or pause the agent. Price per run is unchanged.
• What changed and why: GET /v1/agents/:id/activity (free) is the change log.
• Breaking stories: GET /v1/agents/:id/events (free). Each has a title, summary, importance score (0 to 10), and the keywords added.
• Turn it off: send autopilot: false when you create or update the agent, or PUT /v1/agents/:id/autonomy with { "autopilot": false }. The agent then keeps its setup exactly as you set it. cognition_enabled: false stops self-review entirely, and the agent keeps collecting.
• Proposals are deprecated. GET /v1/agents/:id/proposals and its apply, dismiss, and revert calls still work for now. Read the activity log instead.

One-time agents don't change themselves. See Autopilot.

Spotting the most viral

Raw views mislead. 500,000 views is routine for an account with 10 million followers and huge for one with 3,000. So rank by the Virality Score (weighted_score), as Virlo does for outlier creators and hooks. It rewards beating the follower count by a wide margin, weighted by audience size so one lucky video from a tiny account doesn't top every list.

That 3,000-follower video (167x its followers) scores 41: exceptional. 3,000,000 views on a 1,000,000-follower account (3x) scores 15: promising. Below 1x there's no score (the hooks endpoints show a negative one).

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

To find the real winners:

1. Rank all videos by this score. The videos list can't sort by it, so compute it from views and author.followers. First set aside videos with is_paid: true: they are ads, boosted posts or paid partnerships, so part of their views is ad spend. Report them as ads, not organic wins. The same flag is on trend top_exemplars and hook video objects.
2. Check the plain multiplier: 20 times the follower count is notable, 100 times exceptional, 1,000 times a mega-outlier.
3. Compute engagement_rate = (likes + comments + shares) / views. Above 5% on a big video means people really reacted. Below 1% means passive spread (a popular sound, reposts, or paid promotion).
4. Compare with the AI's picks (analysis_data.top_10_breakdown), which also weigh quality and topic fit. Videos on both lists are the real winners.
5. For whole accounts, sort creator outliers (GET /v1/agents/:id/creators/outliers) by weighted_score (ln(outlier_ratio) × ln(follower_count)), not the raw ratio. They're the best source of rising talent and partnership leads.
6. Check publish_date: a high score this week is a live trend; from months ago, it's history.

Platform benchmarks

Never compare raw views across platforms.

A 100K-view Reel is a bigger deal than a 100K-view TikTok. Spoken insights (hooks, messaging) come mostly from TikTok and YouTube. Instagram publishes no transcripts, so a Reel only has one when Data Intelligence transcribed its audio. Without it, lean on descriptions, hashtags, and the AI's visual analysis.

To read the words themselves, add include_transcript=true to Get videos. TikTok and YouTube transcripts are mostly plain text (source: "platform"). Timestamps always come with the ones Virlo transcribed (source: "transcribed"), which includes every Instagram transcript, and with a small share of platform ones, so check segments.

Reading Data Intelligence fields

With Data Intelligence on, each analyzed video gets AI-written fields (full list). Off-topic, year-old and underperforming videos are skipped. The ones that matter most:

• Hooks. hook_text is the exact opening line. hook_type is its style (question, bold_claim, pov_setup, and more). Use the hooks endpoints, or group your top videos by hook_type and quote real hook_text lines as templates.
• summary is on every analyzed item. Reading 100 summaries is the fastest way to "watch" 100 videos.
• content_format includes free-text values, so group close ones (skit, comedy_skit, skit_sketch).
• Commercial signals (is_sponsored, brands_mentioned[], cta_usages[]) show paid posts, organic brand mentions, and the niche's calls to action. To filter out paid posts, use the row's is_paid, which reads platform labels and caption disclosures.
• Trust checks. Use an item's fields only when intelligence_status is "ready". "skipped" items were left out on purpose and never get fields. Discount anything in low_confidence_fields[]. transcript_word_count: 0 with visual fields filled in means a silent video, not missing data.

Find the winners' pattern. Count each hook_type, content_format, and emotional_tone in the top 25% of videos by Virality Score, then in the bottom 25%. The differences are the niche's real playbook.

Slideshows

TikTok image carousels (slideshows) come back separately from /slideshows, with their own AI fields. In product, education, and lifestyle niches they often beat video.

• panel_texts[] and panel_text_full hold every slide's text in order. That's usually the whole content, so read it like a script you can adapt.
• narrative_arc is how the slides progress. text_density says whether text or images dominate.
• The hook is slide 1. Read hook_text as you would for a video.
• Video-only fields (visual_format, camera_perspective, captions, transcript) are absent by design.

Reading the AI report and trends

GET /v1/agents/:id/analysis/latest returns the AI report in analysis_data:

• key_highlight is the top finding, in one paragraph. overview holds the counts (total_videos analyzed, avg_virality).
• themes[] are groups of what works, each with why_it_works, tactics[], a confidence from 0 to 1, and evidence_video_ids[]. Trust 0.7 and up, check 0.5 to 0.7 against their videos, and call anything lower tentative. Match evidence IDs to the video list so every claim points to real videos.
• timing_analysis shows posting-time patterns, excluded_videos what the AI judged off topic, and connecting_thread the pattern tying the themes together.

GET /v1/agents/:id/trends/latest returns trends, each with a status: new (just appeared, the biggest opportunity), rising (growing, act now), steady (holding), or fading (skip it). On recurring agents, stable_key follows one trend across runs, and the prev_* fields show the change since the last run. A trend moving from new to rising with a growing video_count is the strongest "post about this now" signal.

Trusting audience data

Audience snapshots are built mainly from the people who comment on a creator's videos, not from the follower count. Before you share the numbers:

• confidence_level: high or medium is usable. For low, say "limited signal" and don't present the percentages as fact.
• data_source, strongest first: comments, comments_extended, mixed, followers (TikTok only, never above medium confidence), then profile_only. profile_only means no real signal and is refunded automatically. Treat it as "no data."
• Cost: a snapshot is reused free for 30 days (freshness_days). Only a new one costs $0.50. Asking again while one is being built returns that job for free.

Spending wisely

• Starting work costs money, and so do instant data requests (trends, hashtags, sounds, hooks). Re-reading is free, so first check what your team already has: GET /v1/agents, /v1/satellite/runs, /v1/tracking/creators.
• One well-scoped agent beats three vague ones. Put the effort into keywords, not retries.
• Add up the cost before a plan with several paid steps, and check your balance first (GET /v1/account/balance, free). Top up if it's under $10. The X-Balance-Remaining header only appears on paid responses.
• Vetting many creators? POST /v1/satellite/creators/batch takes up to 25, at $0.50 for each creator it looks up. A creator looked up in the last 6 hours with at least the same options comes back from cache for free.
• X-Cost always shows the full charge. A refund for a failed lookup or an empty post collection arrives after the job ends, as its own row in your usage history.

Live raw data or Virlo analysis?

Raw data routes return live, unprocessed data from TikTok, YouTube Shorts and Instagram Reels, in the same fields on every platform. One call returns one page, with no job to wait for.

• Use raw data for facts about one thing right now: a video's current counts, its comments or transcript, a creator's profile, or what a keyword or hashtag search shows at this moment.
• Use the analysis routes for judgement: trends, outliers and Virality Score (agents and lookups), hooks, sounds and hashtag stats. Raw data has no Virality Score, AI fields or history, and Virlo doesn't save it for you.
• Scope: YouTube search, hashtag and creator videos return Shorts only, and Instagram returns Reels only. Instagram has no transcript. Instagram search returns fewer results per page than TikTok and YouTube.
• Cost: $0.01 per call, so per page, even when the page is empty. Errors are free. Answer from the first page and only fetch more when you need them. To sample a whole niche, one agent run is the better buy than paging through searches.
• Audience sentiment: to learn how people feel about a brand or topic, take an agent's top 10 to 20 on-topic videos and read the first page of comments on each (about $0.20). Score each comment's stance toward the brands or topics you care about, weight by likes, and compare run to run. The video sentiment field only says how the creator feels. See the comment sentiment recipe.
• Content ideas: the same comments, grouped into repeated questions, "part 2" requests and objections, ranked by how many videos they appear on, give an agency a ready list of what to make next. See Content ideas from comments.
• Quick creator vetting: before a deal, read a creator's profile, latest videos and comments on 5 to 10 of them (about $0.10) to check audience tone, red flags and fake-looking engagement. Use a creator lookup for the shortlist. See Quick creator vetting.

Content Trends

Content Trends (/v1/content-trends) are repeatable video formats creators are copying: a structure that stays the same while each creator swaps in their own subject. Virlo's detector finds them and the Virlo team reviews each one before it is published. Pop culture & News (/v1/trends) are topics people are talking about, so use Content Trends to decide what to make and Pop culture & News to decide what to talk about.

• Stages: new (spotted in the last 7 days), rising (10 or more creators this week and at least 1.3 times last week), peaking (in between), fading (under 0.7 times last week) and archived (no posts in 14 days, or fewer than 5 creators in a week once older than 7 days). The list returns live stages unless you ask for archived.
• Momentum: compare creators_7d with creators_prev_7d. The earlier week is counted as it stood a week ago, so the comparison is fair.
• Partial days: the last 7 days of series are marked partial. Videos are found a few days after they are posted (about 4 days at the median), so those days keep rising. A dip there is not a decline.
• Fit: client_fit says whether a format suits a B2B SaaS, clinic, consumer brand or local business, and how to use it. For brands, also filter brand_safety=safe.
• Examples: verified_fit means the video really does the format, and is_paid marks paid posts, which come after organic ones.
• Cost: $0.25 for the list and $0.05 for one trend. Read one trend instead of pulling the list again.