# Intent cookbook

> How to write the one-sentence intent that tells a Content Research Agent which videos to keep, with good and bad examples from real agents.

Source: https://dev.virlo.ai/docs/intent-cookbook
Markdown: https://dev.virlo.ai/docs/intent-cookbook.md
Section: Content Research Agents

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

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**.

**At a glance**

- **What it does:** Tells the agent what counts as on-topic, so it sharpens your keywords and drops videos that don't fit.
- **You send:** One sentence. Aim for 40 to 250 characters (500 max; at least 20 through an AI assistant).
- **You get back:** More on-topic videos and less junk.
- **Cost:** Drafting keywords is free. Each run costs $0.50, or $1.50 with [Data Intelligence](https://dev.virlo.ai/docs/intelligence).
- **How long:** Keyword drafts take seconds. Half of runs collect in under 8 minutes, 9 in 10 in under 20; the AI report adds a few minutes.

## 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](https://dev.virlo.ai/docs/agents#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](https://dev.virlo.ai/docs/mcp) tool names in parentheses).

1. **[Draft keywords](https://dev.virlo.ai/docs/agents#suggest-keywords)** from your intent with `POST /v1/agents/suggest-keywords` (`suggest_keywords`). Free.
2. **[Create the agent](https://dev.virlo.ai/docs/agents#create-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:**

```bash
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"]
  }'
```

**Response:**

```json
{
  "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:**

```bash
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](https://dev.virlo.ai/docs/agents#get-agent), or in [List runs](https://dev.virlo.ai/docs/agents#list-agent-runs).

| Check | Healthy | Needs a fix |
| - | - | - |
| `videos_linked` (videos kept) | A few hundred (about 360; about 200 on later recurring runs) | 20 or fewer |
| Off-topic share: `intent_filtered` ÷ (`videos_linked` + `intent_filtered`) | Some, not most (typically about 30%) | 0% (intent too vague) or over 70% (intent too tight, or keywords off-topic) |
| `intent_match` on each video | A mix of true and false | All `null`: Data Intelligence is off |

Low count? [Get videos](https://dev.virlo.ai/docs/agents#get-agent-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](https://dev.virlo.ai/docs/agents#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.

---

More in Content Research Agents:

- [Overview](https://dev.virlo.ai/docs/agents.md)
- [Autopilot](https://dev.virlo.ai/docs/agents/autopilot.md)
- [Data Intelligence](https://dev.virlo.ai/docs/intelligence.md)