---
title: "Create a new comet configuration"
method: POST
path: "/v1/comet"
tags: ["Comet"]
---

# Create a new comet configuration

`POST /v1/comet`

## Request

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

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

## Request body

- V1CreateCometDto
  - `name` string, required: Name of the custom niche configuration
  - `keywords` string[], 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.
  - `platforms` string[], required: Platforms to scrape from
  - `cadence` string, required: Schedule cadence: "daily", "weekly", "monthly", or a cron expression (minimum daily)
  - `min_views` number: [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_active` boolean: Whether the configuration is active
  - `meta_ads_enabled` boolean: Enable Meta ads collection
  - `exclude_keywords` string[]: 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_strict` boolean: 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.
  - `intent` string: Intent or purpose for this comet configuration
  - `data_intelligence_enabled` boolean: 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_only` boolean: When true (default), only English-language content is collected. Set false to collect content in any language.

## Response `201`

Comet configuration created successfully

- CreateCometResponseDto
  - `data` CometConfigWithJobDto, required
    - `id` string, required
    - `name` string, required
    - `keywords` string[], required
    - `platforms` string[], required
    - `cadence` string, required: Cron expression for scheduling
    - `min_views` number, required
    - `time_range` string, required: today | this_week | this_month | this_year
    - `is_active` boolean, required
    - `is_processing` boolean, required
    - `meta_ads_enabled` boolean, required
    - `data_intelligence_enabled` boolean, required: Whether per-video AI intelligence is enabled. When true, each scheduled run costs $1.50 (base $0.50 + intelligence $1.00).
    - `last_run_at` string, nullable
    - `next_run_at` string, nullable
    - `created_at` string, required
    - `updated_at` string, required
    - `initial_job_id` string, nullable: Initial processing job ID
  - `message` string, required

## Other responses

- `400`: Invalid request parameters
- `401`: Unauthorized - missing or invalid API key
- `429`: Rate limit exceeded (`rate_limit_exceeded`); see the Retry-After header

---

[API](https://skmtc.dev/virlo/apis/virlo-public-api.md) · [All operations](https://skmtc.dev/virlo/apis/virlo-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/virlo/apis/virlo-public-api/revisions/3b69c6145087?raw)