Intent cookbook

A Content Research Agent collects short-form videos on a topic. Keywords decide where it searches. Your intent, one plain sentence, decides which videos it keeps.

What intent does

• Sharpens your keywords. If your keywords are too broad, the agent rewrites each one into a more specific phrase before the first run (sourdough scoring pattern became sourdough scoring patterns home bakers). See them in intent_keywords on Get agent. Changing keywords or intent clears that list until the next run.
• Writes exclude words. If you send no exclude_keywords, the agent writes them from your intent when a run starts. They can include words from your own topic, so check exclude_keywords after the first run.
• Drops off-topic videos. Every run, an AI reads each video's caption, hashtags, and transcript and drops the misses (intent_filtered). It skips this step when the intent is too vague to judge by.
• Marks videos yes or no. With Data Intelligence on (data_intelligence_enabled: true), each kept video gets intent_match: matches true or false plus a short reasoning, judged the same way.

Recurring agents may add news keywords, shown in the run's keyword_breakdown but not in intent_keywords.

The formula

Write one concrete sentence with four parts:

1. Goal: find videos, watch a niche over time, collect hooks, or spot breakout videos.
2. Niche: a specific topic, not one bare word.
3. Content type: tutorials, get-ready-with-me videos, UGC ads, slideshows.
4. Boundary: what to leave out, if it matters.

[Goal] [content type] about [niche], not [what to leave out].

Then add 7 to 12 keywords: multi-word phrases for the same topic, such as home espresso setup and beginner espresso guide. In about 11,000 runs (Aug to Sep 2026), intents of 40 to 250 characters and 7 to 12 keywords were least likely to have over 70% of videos dropped as off-topic.

Exclude words drop any video whose caption, hashtags included, contains one as a whole word: art drops "latte art" and "#art", but not "article". Never use a word from your own topic. For Apple the company, exclude recipe and orchard, not apple the fruit, which almost never appears word for word in a caption.

Good intents

Tidied-up intents from real agents that kept hundreds of videos per run:

• Research a niche: Find beginner morning skincare routines and honest drugstore product reviews, not dermatologist lectures or brand-only ads.
• Sell an app: Find viral Gen Z videos that sell a photo or AI-image mobile app with demos or "this app is called" reveals, not desktop tutorials or generic photo tips.
• Watch over time: Monitor UFC and MMA highlight content to track which fight-night hooks and formats keep winning week over week.

Bad intents

• Keyword dump or list, like Keyword research: jeep, fitness, gym or skin / curly hair / good hooks. It gives the agent nothing to work with.
• Too vague, like I want to find viral video. The agent can't tell on-topic from off-topic, so junk gets through.
• Thin keywords: a precise intent with 1 to 3 generic keywords. The intent drops most of what they find, and about 1 run in 5 ends with 20 videos or fewer.
• Wrong language: turning off english_only but writing the intent and keywords in English. The agent searches in the language you write in, so you still get mostly English. Write in the language you want.

Step by step

Same steps via the API or an AI assistant (MCP tool names in parentheses).

1. Draft keywords from your intent with POST /v1/agents/suggest-keywords (suggest_keywords). Free.
2. Create the agent with the same intent: POST /v1/agents (search_keywords once, create_niche_monitor on repeat). $0.50 a run, $1.50 with Data Intelligence.
3. Wait. Check GET /v1/agents/:id (get_keyword_search_results or get_niche_monitor_data) every 30 seconds (polling, free) until finalized is true: the run and its AI report are done.

curl -X POST https://api.virlo.ai/v1/agents/suggest-keywords \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "intent": "Find what is working in home espresso content for beginners, not barista competition clips",
    "platforms": ["tiktok", "youtube"]
  }'

{
  "data": {
    "keywords": [
      "home espresso setup",
      "beginner espresso guide",
      "espresso machine review",
      "easy espresso recipe",
      "latte art for beginners",
      "budget espresso machine",
      "espresso tips home",
      "grinding coffee at home",
      "espresso puck prep",
      "home barista basics"
    ],
    "exclude_keywords": ["competition", "championship", "pro", "advanced", "expert", "latteart", "battle", "world"],
    "reasoning": "This set focuses on beginner-friendly home espresso content by including terms like 'setup', 'guide', and 'easy', while excluding professional competition and cafe-related terms to avoid off-topic results.",
    "quality": {
      "score": 100,
      "passes": true,
      "issues": [],
      "stats": {
        "count": 10,
        "avg_words_per_keyword": 3.2,
        "single_word_count": 0,
        "long_keyword_count": 0,
        "duplicate_count": 0,
        "core_token_coverage": 0.7,
        "core_token": "espresso"
      }
    },
    "timely_context_used": false
  }
}

Check it first. Excluding latteart drops the #latteart videos that latte art for beginners should find, so cut it. quality grades the keyword set, not your intent: a vague intent like coffee can still score 100. If quality.passes is false, read quality.issues, then sharpen the intent or fix the flagged keywords.

Creating the agent starts its run. For intent_match on each video ($1.50 a run), add "data_intelligence_enabled": true.

curl -X POST https://api.virlo.ai/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_recurring": false,
    "name": "Home Espresso for Beginners",
    "intent": "Find what is working in home espresso content for beginners, not barista competition clips",
    "keywords": ["home espresso setup", "beginner espresso guide", "budget espresso machine", "latte art for beginners", "espresso puck prep", "home barista basics", "espresso tips home"],
    "exclude_keywords": ["competition", "championship", "pro", "advanced", "expert", "battle", "world"],
    "platforms": ["tiktok", "youtube"]
  }'

How to tell it worked

Read the run's numbers in latest_run on Get agent, or in List runs.

Low count? Get videos may list more than the run's count. The run's keyword_breakdown shows what each keyword found.

On Get videos, the intent_match=true filter's total covers one page only. To count all matches, page through without the filter and count intent_match.matches: true.

If results look off:

1. Sharpen the intent: add a content type and a boundary.
2. Refresh keywords: call suggest-keywords with mode: "refresh" and the current keywords in existing_keywords.
3. Apply them: use Update agent on a recurring agent. A one-time agent never runs again, so create a new one (charged again).

Single-word keywords pull in more off-topic videos.