Comet - Custom Niche

The Comet endpoint suite enables you to create custom niche configurations that automatically discover and organize videos, ads, and creator outliers based on your specific keywords and criteria. Set up recurring scraping jobs with flexible scheduling, platform targeting, and filtering options. Perfect for monitoring specific topics, competitors, or content themes over time.

All Comet V1 endpoints use the /v1 base path and snake_case for all parameter and response field names. Responses are wrapped in a {"data": {...}} envelope.

POST/v1/comet

Create comet

Creates a new custom niche configuration that will automatically scrape videos based on your provided keywords, platforms, and scheduling settings. The configuration runs on the specified cadence and collects videos matching your criteria.

Cost per request:

Request body

Name
name
Type
string
Required
*
Description
A descriptive name for this configuration. Example: "Tech Reviews" or "AI Content Tracker"
Name
keywords
Type
string[]
Required
*
Description
Array of keywords to search for (1-20 keywords). Example: ["tech review", "gadget review", "product review"]
Pro tip: Use specific multi-word phrases for better results. Avoid generic single words.
Name
platforms
Type
string[]
Required
*
Description
Platforms to scrape from. Options: youtube, tiktok, instagram. Must include at least one platform.
Name
cadence
Type
string
Required
*
Description
Schedule cadence. Options:
- Simple: "daily", "weekly", "monthly"
- Cron expression: Any valid cron (minimum daily frequency)
Examples: "daily" or "0 0 * * *" (midnight daily)
Name
min_views
Type
integer
Required
*
Description
Minimum view count threshold for videos. Videos below this threshold will be filtered out. Must be >= 0.
Name
time_range
Type
string
Required
*
Description
Time period filter for video publish date. Options: today, this_week, this_month, this_year.
Name
is_active
Type
boolean
Description
Whether the configuration is active. Defaults to true. Set to false to create a paused configuration.
Name
meta_ads_enabled
Type
boolean
Description
Enable Meta ads collection for this configuration. Defaults to false. When enabled, the system will collect Meta ads related to your keywords.
Name
exclude_keywords
Type
string[]
Description
Keywords to exclude from video results. Videos containing these keywords in their title will be filtered out. Example: ["spam", "clickbait"]
Name
exclude_keywords_strict
Type
boolean
Description
If true, also check video transcript for exclude_keywords matching. Defaults to false. Only checks titles when false.

Request

POST

/v1/comet

curl -X POST https://api.virlo.ai/v1/comet \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Reviews",
    "keywords": ["tech review", "gadget review", "product review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "daily",
    "min_views": 10000,
    "time_range": "this_week",
    "is_active": true,
    "meta_ads_enabled": false,
    "exclude_keywords": ["spam", "clickbait"],
    "exclude_keywords_strict": false
  }'

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Tech Reviews",
    "keywords": ["tech review", "gadget review", "product review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "0 0 * * *",
    "min_views": 10000,
    "time_range": "this_week",
    "is_active": true,
    "is_processing": true,
    "meta_ads_enabled": false,
    "last_run_at": null,
    "next_run_at": "2025-01-16T00:00:00.000Z",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z",
    "initial_job_id": "467727a3-3b38-4e1f-beed-332b98ffbb55"
  },
  "message": "Comet configuration created successfully"
}

GET/v1/comet

List comets

Retrieves a list of all your comet configurations. By default, only active configurations are returned. Use the include_inactive parameter to see all configurations including deactivated ones.

Cost per request:

Query parameters

Name
include_inactive
Type
string
Description
Include inactive configurations in the results. Set to "true" to include all configurations. Defaults to showing only active ones.

Request

GET

/v1/comet

curl -G https://api.virlo.ai/v1/comet \
  -H "Authorization: Bearer {token}" \
  -d include_inactive=true

Response

{
  "data": {
    "total": 2,
    "configurations": [
      {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "name": "Tech Reviews",
        "keywords": ["tech review", "gadget review"],
        "platforms": ["youtube", "tiktok"],
        "cadence": "0 0 * * *",
        "min_views": 10000,
        "time_range": "this_week",
        "is_active": true,
        "is_processing": false,
        "meta_ads_enabled": false,
        "last_run_at": "2025-01-15T00:00:00.000Z",
        "next_run_at": "2025-01-16T00:00:00.000Z",
        "created_at": "2025-01-15T10:30:00.000Z",
        "updated_at": "2025-01-15T10:30:00.000Z",
        "user_email": "[email protected]",
        "user_id": null
      },
      {
        "id": "987f6543-e21b-34d5-c678-789012345678",
        "name": "Gaming Content",
        "keywords": ["gaming", "gameplay"],
        "platforms": ["youtube"],
        "cadence": "0 0 * * 0",
        "min_views": 50000,
        "time_range": "this_month",
        "is_active": false,
        "is_processing": false,
        "meta_ads_enabled": true,
        "last_run_at": "2025-01-10T00:00:00.000Z",
        "next_run_at": null,
        "created_at": "2025-01-10T08:00:00.000Z",
        "updated_at": "2025-01-14T12:00:00.000Z",
        "user_email": "[email protected]",
        "user_id": null
      }
    ]
  }
}

GET/v1/comet/:id

Get comet

Retrieves a specific comet configuration by its unique ID. Returns detailed information including the schedule, filtering criteria, and execution history. The response shape matches a single item from the list endpoint.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration. Example: 123e4567-e89b-12d3-a456-426614174000

Request

GET

/v1/comet/:id

curl https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Tech Reviews",
    "keywords": ["tech review", "gadget review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "0 0 * * *",
    "min_views": 10000,
    "time_range": "this_week",
    "is_active": true,
    "is_processing": false,
    "meta_ads_enabled": false,
    "last_run_at": "2025-01-15T00:00:00.000Z",
    "next_run_at": "2025-01-16T00:00:00.000Z",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T10:30:00.000Z"
  }
}

PUT/v1/comet/:id

Update comet

Updates an existing comet configuration. All required fields (name, keywords, platforms, cadence, min_views, time_range) must be provided in the request body. This is a full replacement, so include all values you want to keep.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration to update. Example: 123e4567-e89b-12d3-a456-426614174000

Request body

All required fields must be provided. Optional fields can be included to update them.

Name
name
Type
string
Required
*
Description
Configuration name.
Name
keywords
Type
string[]
Required
*
Description
Keywords array (1-20 keywords).
Name
platforms
Type
string[]
Required
*
Description
Platforms to scrape from.
Name
cadence
Type
string
Required
*
Description
Scheduling cadence ("daily", "weekly", "monthly", or cron expression).
Name
min_views
Type
integer
Required
*
Description
Minimum view count threshold.
Name
time_range
Type
string
Required
*
Description
Time range filter.
Name
is_active
Type
boolean
Description
Activate or deactivate the configuration.
Name
meta_ads_enabled
Type
boolean
Description
Enable or disable Meta ads collection.
Name
exclude_keywords
Type
string[]
Description
Update the keywords to exclude from results.
Name
exclude_keywords_strict
Type
boolean
Description
Update whether to check transcripts for excluded keywords.

Request

PUT

/v1/comet/:id

curl -X PUT https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Tech Reviews Updated",
    "keywords": ["tech review", "gadget review", "phone review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "weekly",
    "min_views": 50000,
    "time_range": "this_month"
  }'

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Tech Reviews",
    "keywords": ["tech review", "gadget review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "0 0 * * 0",
    "min_views": 50000,
    "time_range": "this_month",
    "is_active": true,
    "is_processing": false,
    "meta_ads_enabled": false,
    "last_run_at": "2025-01-15T00:00:00.000Z",
    "next_run_at": "2025-01-21T00:00:00.000Z",
    "created_at": "2025-01-15T10:30:00.000Z",
    "updated_at": "2025-01-15T12:00:00.000Z"
  },
  "message": "Comet configuration updated successfully"
}

DELETE/v1/comet/:id

Delete comet

Soft-deletes a comet configuration. The configuration will no longer be scheduled for scraping. Returns 204 No Content on success.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration to delete. Example: 123e4567-e89b-12d3-a456-426614174000

Request

DELETE

/v1/comet/:id

curl -X DELETE https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000 \
  -H "Authorization: Bearer {token}"

Response

// No response body

GET/v1/comet/:id/videos

Get comet videos

Retrieves all videos that have been linked to a specific comet configuration. Supports comprehensive filtering, pagination, and sorting options to help you analyze your collected video data.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration. Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

Name
limit
Type
integer
Description
Maximum number of videos to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
min_views
Type
integer
Description
Filter videos by minimum view count. Example: 10000
Name
platforms
Type
string
Description
Filter by platform(s). Comma-separated string. Options: youtube, tiktok, instagram. Example: "youtube,tiktok"
Name
start_date
Type
string
Description
Filter videos published after this date (ISO 8601). Example: "2025-01-01T00:00:00Z"
Name
end_date
Type
string
Description
Filter videos published before this date (ISO 8601). Example: "2025-12-31T23:59:59Z"
Name
order_by
Type
string
Description
Field to sort by. Options: publish_date, views, created_at.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/comet/:id/videos

curl -G https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000/videos \
  -H "Authorization: Bearer {token}" \
  -d min_views=50000 \
  -d platforms=youtube,tiktok \
  -d order_by=views \
  -d sort=desc \
  -d limit=20 \
  -d page=1

Response

{
  "data": {
    "custom_niche_id": "123e4567-e89b-12d3-a456-426614174000",
    "custom_niche_name": "Tech Reviews",
    "total": 150,
    "limit": 20,
    "offset": 0,
    "videos": [
      {
        "id": "0c675286-d6e9-413f-9ff5-24138c6e2ff6",
        "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
        "description": "Best Tech Review 2025 #tech #review",
        "hashtags": ["#tech", "#review"],
        "publish_date": "2025-01-14T15:30:00",
        "created_at": "2025-01-14T16:00:00.000000",
        "views": 125000,
        "number_of_comments": 45,
        "number_of_likes": 3200,
        "number_of_shares": null,
        "thumbnail_url": "6c3c9450-4db7-47b9-8af4-ccb03ef5d455.jpg",
        "type": "youtube",
        "niche": "gaming",
        "author": {
          "id": "90f86161-6818-4bed-94d2-52ba9f20724b",
          "username": "tiffy.cooks",
          "verified": true,
          "followers": 2142089,
          "avatar_url": "https://example.com/avatar.jpg"
        }
      }
    ]
  }
}

GET/v1/comet/:id/ads

Get comet ads

Retrieves all Meta ads that have been collected for a specific comet configuration. This endpoint requires that meta_ads_enabled is set to true on the configuration. Supports pagination and sorting options to help you analyze collected advertising data.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration. Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

Name
limit
Type
integer
Description
Maximum number of ads to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
order_by
Type
string
Description
Field to sort by. Options: created_at, page_like_count. Default is created_at.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/comet/:id/ads

curl -G https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000/ads \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d order_by=page_like_count \
  -d sort=desc

Response

{
  "data": {
    "custom_niche_id": "123e4567-e89b-12d3-a456-426614174000",
    "custom_niche_name": "Tech Reviews",
    "total": 25,
    "limit": 50,
    "offset": 0,
    "ads": [
      {
        "id": "5f9d1551-2cd4-441d-bb36-c150fbcc27c7",
        "ad_archive_id": "4362525100698401",
        "page_id": "101720278791083",
        "page_profile_url": "https://www.facebook.com/TechCompanyInc/",
        "page_profile_picture_url": "https://example.com/page-avatar.jpg",
        "is_active": true,
        "start_date": "2025-01-10",
        "end_date": "2025-02-10",
        "url": "https://www.facebook.com/ads/library?id=4362525100698401",
        "caption": "techcompany.com",
        "body": "Check out our latest product launch! Revolutionary tech that will change how you work.",
        "cta_type": "SHOP_NOW",
        "page_like_count": 150000,
        "title": "New Product Launch",
        "video_url": "https://example.com/ad-video.mp4",
        "created_at": "2025-01-14T15:30:00.000Z",
        "linked_at": "2025-01-14T15:30:01.000Z"
      }
    ]
  }
}

GET/v1/comet/:id/creators/outliers

Get creator outliers

Retrieves creator outliers identified for a specific comet configuration. Outliers are creators whose content performance significantly exceeds their typical metrics, indicating breakout potential. Results include outlier ratios, follower counts, average views, topic analysis, and the specific videos that contributed to the outlier detection.

Cost per request:

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration. Example: 123e4567-e89b-12d3-a456-426614174000

Query parameters

Name
limit
Type
integer
Description
Maximum number of outliers to return (1-100). Default is 50.
Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
order_by
Type
string
Description
Field to sort by. Options: outlier_ratio, avg_views, follower_count. Default is outlier_ratio.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.
Name
platform
Type
string
Description
Filter by a single platform. Options: youtube, tiktok, instagram.

Request

GET

/v1/comet/:id/creators/outliers

curl -G https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000/creators/outliers \
  -H "Authorization: Bearer {token}" \
  -d limit=50 \
  -d page=1 \
  -d order_by=outlier_ratio \
  -d sort=desc \
  -d platform=youtube

Response

{
  "data": {
    "comet_id": "123e4567-e89b-12d3-a456-426614174000",
    "comet_name": "Tech Reviews",
    "total": 25,
    "limit": 50,
    "offset": 0,
    "hasMore": false,
    "outliers": [
      {
        "creator_url": "https://youtube.com/@tech_creator",
        "creator_avatar_url": "https://yt3.googleusercontent.com/example-tech-creator-avatar",
        "follower_count": 50000,
        "avg_views": 2500000,
        "outlier_ratio": 50.0,
        "videos_analyzed": 12,
        "creator_topics": ["tech reviews", "gadgets"],
        "matching_topics": ["tech reviews"],
        "platform": "youtube",
        "identified_at": "2025-01-15T10:30:00.000Z",
        "videos": [
          {
            "id": "7606705096256261406",
            "title": "This $50 Gadget Changed Everything",
            "description": "I found the most underrated tech product of 2025...",
            "views": 5200000,
            "likes": 180000,
            "comments": 12000,
            "publish_date": "2025-01-10T14:00:00.000Z",
            "hashtags": ["tech", "gadgets", "review"]
          }
        ]
      },
      {
        "creator_url": "https://youtube.com/@gadget_guru",
        "creator_avatar_url": "https://yt3.googleusercontent.com/example-gadget-guru-avatar",
        "follower_count": 120000,
        "avg_views": 1800000,
        "outlier_ratio": 15.0,
        "videos_analyzed": 8,
        "creator_topics": ["gadget reviews", "unboxing", "tech"],
        "matching_topics": ["gadget reviews"],
        "platform": "youtube",
        "identified_at": "2025-01-15T10:30:00.000Z",
        "videos": [
          {
            "id": "9182736450918273645",
            "title": "Unboxing the Most Requested Tech of 2025",
            "description": "You asked for it, here it is...",
            "views": 3600000,
            "likes": 95000,
            "comments": 7800,
            "publish_date": "2025-01-12T09:30:00.000Z",
            "hashtags": ["unboxing", "tech", "gadgets"]
          }
        ]
      }
    ]
  }
}

Usage workflow

The Comet custom niche system follows a straightforward workflow:

Create configuration: POST to /v1/comet with your keywords (max 20), platforms, and scheduling preferences
Save the ID: Store the returned configuration id for future reference
Monitor execution: Use GET /v1/comet/:id to check when the configuration last ran and when it will run next
List configurations: GET /v1/comet to see all your custom niche configurations
Retrieve videos: GET /v1/comet/:id/videos to access all collected videos with flexible filtering
Retrieve ads (optional): GET /v1/comet/:id/ads to access collected Meta ads if meta_ads_enabled is true
Discover creators: GET /v1/comet/:id/creators/outliers to find breakout creators in your niche
Update as needed: PUT /v1/comet/:id to modify keywords, scheduling, or filters
Delete when done: DELETE /v1/comet/:id to soft-delete the configuration

The configuration runs automatically on your specified cadence (daily, weekly, monthly, or custom cron). Each execution collects videos matching your criteria and makes them available through the videos endpoint. If Meta ads collection is enabled, related ads will also be collected and accessible through the ads endpoint. Creator outliers are identified automatically and surfaced through the outliers endpoint.

Scheduling options

Simple cadences

Use these convenient shortcuts for common scheduling patterns:

"daily" - Runs once per day at midnight UTC (equivalent to "0 0 * * *")
"weekly" - Runs once per week on Sunday at midnight UTC (equivalent to "0 0 * * 0")
"monthly" - Runs once per month on the 1st at midnight UTC (equivalent to "0 0 1 * *")

Cron expressions

For more control, use cron expressions with a minimum frequency of once per day:

┌───────────── minute (0 - 59)
│ ┌───────────── hour (0 - 23)
│ │ ┌───────────── day of month (1 - 31)
│ │ │ ┌───────────── month (1 - 12)
│ │ │ │ ┌───────────── day of week (0 - 6) (Sunday to Saturday)
│ │ │ │ │
* * * * *

Examples:

"0 9 * * *" - Every day at 9:00 AM UTC
"0 0,12 * * *" - Twice daily at midnight and noon UTC
"0 0 * * 1,4" - Every Monday and Thursday at midnight UTC
"30 14 1 * *" - 1st of every month at 2:30 PM UTC

Note: Cadence expressions with a frequency higher than once per day (e.g., every hour) are not supported to prevent excessive API usage.

Best practices

Keyword selection

Use specific phrases: Multi-word keywords like "tech product review" yield better results than single words like "tech"
Avoid ambiguous terms: Generic words return scattered, unrelated content
Combine related keywords: Group variations like ["iPhone review", "iPhone unboxing", "iPhone tutorial"]
Stay within limits: Maximum 20 keywords per configuration
Test and refine: Start with a few keywords, check the results, then expand or adjust

Platform targeting

YouTube: Best for long-form content, tutorials, reviews
TikTok: Optimal for short-form viral content, trends
Instagram: Great for visual content, creator posts

Use all platforms for comprehensive coverage, or target specific platforms based on your content needs.

View thresholds

Low threshold (0-10k): Captures emerging content and smaller creators
Medium threshold (10k-100k): Filters for proven performers with solid engagement
High threshold (100k+): Focuses on viral hits and top-performing content

Adjust min_views based on your quality vs. quantity preference.

Time ranges

today: Most recent content, often still gaining traction
this_week: Balance of fresh content with established engagement
this_month: Proven performers with substantial data
this_year: Long-term trends and evergreen content

Match the time range to your analysis goals and update frequency.

Scheduling strategy

Daily: Best for fast-moving topics, news, trends
Weekly: Good for regular monitoring without overwhelming data
Monthly: Suitable for slow-moving niches or periodic reports
Custom cron: Advanced scheduling for specific times or days

Consider your analysis frequency and data processing capacity when choosing a cadence.

Use cases

Content monitoring

Track specific topics or themes over time:

{
  name: "AI Content Trends",
  keywords: ["ChatGPT", "AI tools", "artificial intelligence"],
  platforms: ["youtube", "tiktok"],
  cadence: "daily",
  min_views: 10000,
  time_range: "this_week"
}

Competitor analysis

Monitor competitors' content performance:

{
  name: "Competitor Tracking",
  keywords: ["competitor brand", "competitor product", "vs competitor"],
  platforms: ["youtube", "tiktok", "instagram"],
  cadence: "weekly",
  min_views: 50000,
  time_range: "this_month"
}

Niche discovery

Explore emerging content verticals:

{
  name: "Emerging Gaming Trends",
  keywords: ["new game", "indie game", "game release"],
  platforms: ["youtube"],
  cadence: "0 0 * * 1",  // Monday mornings
  min_views: 5000,
  time_range: "this_week"
}

Brand mentions

Track how your brand is discussed:

{
  name: "Brand Mentions",
  keywords: ["your brand", "your product", "your company"],
  platforms: ["youtube", "tiktok", "instagram"],
  cadence: "daily",
  min_views: 0,  // Catch all mentions
  time_range: "today"
}

Industry research

Analyze broad industry trends:

{
  name: "SaaS Industry Trends",
  keywords: ["SaaS tools", "B2B software", "productivity apps"],
  platforms: ["youtube"],
  cadence: "monthly",
  min_views: 100000,
  time_range: "this_month"
}

Creator outreach

Discover breakout creators for partnership opportunities:

// 1. Create a comet to track your niche
// POST /v1/comet
{
  name: "Fitness Creator Discovery",
  keywords: ["home workout", "fitness routine", "gym tips"],
  platforms: ["youtube", "tiktok", "instagram"],
  cadence: "weekly",
  min_views: 5000,
  time_range: "this_month"
}

// 2. After data is collected, fetch creator outliers
// GET /v1/comet/:id/creators/outliers?order_by=outlier_ratio&sort=desc&limit=10

Error responses

The Comet endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include:
- Missing required fields (name, keywords, platforms, cadence, min_views, time_range)
- Keywords array exceeding 20 elements
- Invalid platform values (must be youtube, tiktok, or instagram)
- Invalid time_range value
- Invalid cadence format
- min_views less than 0
- Invalid pagination parameters
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
404 Not Found
Description
Comet configuration not found. The specified ID doesn't exist or you don't have access to it.
Name
429 Too Many Requests
Description
Rate limit exceeded. Your plan has specific rate limits per endpoint. Wait before making additional requests.