Comet

Create a new comet configuration

Creates a new custom niche configuration with keywords, platforms, and scheduling.

post/v1/comet

Request

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

Request body

namestring required

Name of the custom niche configuration

keywordsstring[] required

Array of keywords to search for (1-20 keywords). Hashtag-style tokens are normalised: a leading "#" is stripped and whitespace collapsed, so "#progressivehouse" and "progressivehouse" are equivalent.

platformsstring[] required

Platforms to scrape from

cadencestring required

Schedule cadence: "daily", "weekly", "monthly", or a cron expression (minimum daily)

min_viewsnumber

[Deprecated] Previously set the scrape-time minimum view threshold. Collection scope is now system-managed — recurring agents collect the widest relevant net each cycle so no content is missed, and you filter by views at READ time on GET /v1/comet/:comet_id/videos (min_views). Still accepted for backward compatibility but has NO effect on what gets collected.

time_range'today' | 'this_week' | 'this_month' | 'this_year'

[Deprecated] Previously set the scrape-time publish-date window. Collection scope is now system-managed and cadence-aware (a weekly agent scans the past week, a monthly agent the past month, etc.), and you filter by date at READ time on GET /v1/comet/:comet_id/videos (start_date / end_date). Still accepted for backward compatibility but has NO effect on what gets collected.

is_activeboolean

Whether the configuration is active

meta_ads_enabledboolean

Enable Meta ads collection

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.

intentstring

Intent or purpose for this comet configuration

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) to the $0.50 base, so $1.50 per run in total.

english_onlyboolean

When true (default), only English-language content is collected. Set false to collect content in any language.

Example request

{
  "name": "Tech Reviews",
  "keywords": [
    "progressive house",
    "#melodictechno"
  ],
  "platforms": [
    "youtube",
    "tiktok"
  ],
  "cadence": "daily",
  "min_views": 10000,
  "time_range": "this_week",
  "is_active": true,
  "meta_ads_enabled": true,
  "exclude_keywords": [
    "recipe",
    "fruit",
    "orchard"
  ],
  "intent": "Find trending tech review content for Q1 campaign"
}

Response

Comet configuration created successfully

messagestring required

Example response

{
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Fitness Niche Monitor",
    "keywords": [
      "fitness",
      "workout"
    ],
    "platforms": [
      "tiktok",
      "youtube"
    ],
    "cadence": "0 */6 * * *",
    "min_views": 1000,
    "time_range": "this_week",
    "is_active": true,
    "meta_ads_enabled": true,
    "last_run_at": "2026-01-15T10:30:00.000Z",
    "next_run_at": "2026-01-16T04:00:00.000Z",
    "created_at": "2026-01-10T08:00:00.000Z",
    "updated_at": "2026-01-15T10:30:00.000Z"
  },
  "message": "Comet configuration created successfully"
}

Changes

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