Content Research Agents

Create a content research agent

Creates a one-shot (is_recurring=false) or recurring (is_recurring=true) agent and dispatches its first run immediately. Collection scope is system-managed — filter by views/date at read time.

post/v1/agents

Request

Base URL: https://api.virlo.ai
URL: https://api.virlo.ai/v1/agents
Auth: HTTP bearer

Request body

is_recurringboolean required

Whether the agent runs on a schedule (true) or once (false). Recurring agents require cadence.

intentstring required

What you want this agent to research, in plain language. Drives keyword quality, on-topic filtering, and the agent’s self-optimization. Required.

keywordsstring[] required

Keywords to search for (1-50). Hashtag-style tokens are normalised (a leading "#" is stripped, whitespace collapsed). Autopilot always keeps every keyword you send and only adds around them.

namestring

Human-friendly name for the agent.

platformsstring[]

Platforms to collect from.

cadencestring

Schedule cadence for recurring agents: "daily", "weekly", "monthly", or a cron expression (minimum daily). Required when is_recurring=true. On a one-time agent (is_recurring=false) it is ignored without being validated, and the agent comes back with cadence null.

exclude_keywordsstring[]

Noise terms to filter out — matched as WHOLE WORDS against captions + hashtags, so use the single word people actually type for the OTHER meaning (researching Apple the company, not the fruit? exclude recipe, fruit, orchard), not multi-word phrases like apple the fruit (which never match). Never exclude a word that is part of your own topic. Tip: suggest-keywords returns a ready exclude_keywords list you can pass straight in.

exclude_keywords_strictboolean

If true, also match exclude_keywords against the video transcript (speech), not just the caption/hashtags — use when the noise word is spoken but rarely written. Default false.

meta_ads_enabledboolean

Enable Meta ads collection (adds the meta_ads platform).

data_intelligence_enabledboolean

Enable per-video AI intelligence: 79 structured fields per analyzed video and 70 per analyzed slideshow, covering topics, hooks, sentiment, brand safety, on-screen people and AI provenance. Not every item is analyzed: content that is off-intent, more than a year old (unless among the run's top performers), or that got no more views than its creator has followers is skipped and returns intelligence_status: "skipped". Adds $1.00 (100 credits) per run on top of the $0.50 base, so $1.50 per run in total. Recurring agents (is_recurring: true) pay it on every run, not at creation.

english_onlyboolean

When true (default), only English-language content is collected. Set false to collect content in any language — keywords are generated in the language of your agent name and intent.

autopilotboolean

Autopilot keeps a recurring agent finding new videos after each run: it rewords searches, adds keywords and follows breaking stories in your niche. On by default. It never removes a keyword or exclude term you set and never adds charges. Set false to keep the configuration exactly as you send it. One-time agents are unaffected.

Example request

{
  "is_recurring": true,
  "intent": "Track viral protein-recipe content for a fitness brand",
  "keywords": [
    "protein recipe",
    "#highprotein"
  ],
  "name": "Protein Recipes",
  "platforms": [
    "youtube",
    "tiktok",
    "instagram"
  ],
  "cadence": "weekly",
  "exclude_keywords": [
    "recipe",
    "fruit",
    "orchard"
  ]
}

Response

Agent created

messagestring required

Example response

{
  "data": {
    "keywords": [
      "protein recipes",
      "meal prep"
    ],
    "platforms": [
      "tiktok",
      "youtube",
      "instagram"
    ],
    "intent_keywords": [
      "high protein recipe",
      "protein meal prep",
      "protein dessert"
    ],
    "pinned_keywords": [
      "protein recipe",
      "highprotein"
    ],
    "latest_run": {
      "keyword_breakdown": [
        {
          "keyword": "high protein recipe",
          "videos_inserted": 41,
          "videos_updated": 12,
          "tiktok_count": 27,
          "youtube_count": 12,
          "instagram_count": 2
        }
      ]
    }
  },
  "message": "Agent created"
}

Changes

No recorded changes to this operation across all 1 revision of this API.