Comet - Custom Niche

The Comet endpoint suite enables you to create custom niche configurations that automatically discover and organize videos, slideshows, 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.

Pricing: Creating or running a Comet costs $0.50 per execution (initial creation + each scheduled run). All read endpoints — videos, ads, creator outliers — are free and included with your Comet. See Billing & Pricing.

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:$0.50(charged when processing completes)

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.
Name
intent
Type
string
Description
Intent or purpose for the configuration. Use it to describe the goal behind this niche. When combined with data_intelligence_enabled: true, the intent triggers a post-intelligence evaluation step: after the 40+ structured intelligence fields are populated, each video is evaluated against your intent and receives an intent_match result. Example: "Find trending tech review content for Q1 campaign"
Name
data_intelligence_enabled
Type
boolean
Description
Enable per-video AI intelligence. When true, each scheduled run analyzes videos with 40+ structured fields including topics, hooks, emotional tone, brand safety, visual format, CTAs, and more. Adds +$1.00 per scheduled run ($1.50 total per cycle). See Data Intelligence for the full field reference. Default: 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,
    "intent": "Find trending tech review content for Q1 campaign"
  }'

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,
    "intent": "Find trending tech review content for Q1 campaign",
    "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:Free

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:Free

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,
    "intent": "Find trending tech review content for Q1 campaign",
    "intent_summary": {
      "matched": 95,
      "total_evaluated": 148,
      "not_evaluated": 2,
      "matched_urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]
    },
    "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",
    "analysis": "Bootstrapped founders dominated this week with unsexy-profitability narratives: waste management, B2B SaaS, and niche product validation drove 80M+ combined views.",
    "analysis_data": {
      "themes": [
        {
          "stable_key": "unsexy-profitability",
          "name": "Unsexy Profitability (Waste Management, B2B, SaaS)",
          "why_it_works": "Reframes success away from vanity brands; audiences crave permission to build boring, scalable businesses.",
          "video_count": 8,
          "evidence_video_ids": ["0c675286-d6e9-413f-9ff5-24138c6e2ff6", "..."],
          "tactics": ["founder-led monologue", "screenshot of revenue dashboard"],
          "confidence": 0.88
        }
      ],
      "viral_tactics": ["..."],
      "timing_analysis": { "peak_hours": [14, 20], "pattern": "..." }
    },
    "analysis_batch_start": "2025-01-09T00:00:00.000Z",
    "analysis_batch_end": "2025-01-15T00:00:00.000Z"
  }
}

PUT/v1/comet/:id

Update comet

Updates an existing comet configuration. All fields are optional — only include the fields you want to change. Omitted fields retain their current values.

Cost per request:Free

Path parameters

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

Request body

All fields are optional. Only include the fields you want to update.

Name
name
Type
string
Description
Configuration name.
Name
keywords
Type
string[]
Description
Keywords array (1-20 keywords).
Name
platforms
Type
string[]
Description
Platforms to scrape from.
Name
cadence
Type
string
Description
Scheduling cadence ("daily", "weekly", "monthly", or cron expression).
Name
min_views
Type
integer
Description
Minimum view count threshold.
Name
time_range
Type
string
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.
Name
intent
Type
string
Description
Intent or purpose for the configuration.

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",
    "min_views": 50000
  }'

Response

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "Tech Reviews Updated",
    "keywords": ["tech review", "gadget review"],
    "platforms": ["youtube", "tiktok"],
    "cadence": "0 0 * * *",
    "min_views": 50000,
    "time_range": "this_week",
    "is_active": true,
    "is_processing": false,
    "meta_ads_enabled": false,
    "intent": "Find trending tech review content for Q1 campaign",
    "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-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:Free

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:Free(included with Comet creation)

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.
Name
intent_match
Type
string
Description
Filter videos by intent match result. Set to true to return only videos that matched the intent, or false for non-matches. Requires the comet to have both intent and data_intelligence_enabled: true. Omit to return all videos regardless of match status.

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"
        },
        "intent_match": {
          "matches": true,
          "reasoning": "Video is a tech product review (primary_topic: tech review) with educational tone and product closeup format, matching the intent to find trending tech review content."
        }
      }
    ]
  }
}

GET/v1/comet/:id/slideshows

Get comet slideshows

Retrieves all slideshows (image carousels) that have been linked to a specific comet configuration. Accepts the same query parameters as the comet videos endpoint. Supports comprehensive filtering, pagination, and sorting options.

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 slideshows 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 slideshows by minimum view count. Example: 10000
Name
start_date
Type
string
Description
Filter slideshows published after this date (ISO 8601). Example: "2025-01-01T00:00:00Z"
Name
end_date
Type
string
Description
Filter slideshows 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. Default is views.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/comet/:id/slideshows

curl -G https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000/slideshows \
  -H "Authorization: Bearer {token}" \
  -d min_views=50000 \
  -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": "IA",
    "total": 85,
    "limit": 20,
    "offset": 0,
    "slideshows": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "url": "https://www.tiktok.com/@user/photo/456",
        "description": "This is insane #trending #fyp",
        "platform": "tiktok",
        "views": 185000,
        "likes": 15200,
        "shares": 1800,
        "comments": 95,
        "bookmarks": 2100,
        "publish_date": "2025-01-14T12:30:00+00:00",
        "created_at": "2025-01-14T13:00:00.000000",
        "linked_at": "2025-01-14T13:00:01.000000",
        "hashtags": ["trending", "fyp"],
        "thumbnail_url": "https://example.com/thumb.jpg",
        "images": [
          { "image_url": "https://example.com/img1.webp", "position": 0 },
          { "image_url": "https://example.com/img2.webp", "position": 1 },
          { "image_url": "https://example.com/img3.webp", "position": 2 }
        ],
        "type": "tiktok",
        "author": {
          "username": "creator_name",
          "verified": true,
          "followers": 54000,
          "avatar_url": "https://example.com/avatar.jpg"
        },
        "keyword_found_by": "trending AI tools",
        "is_eligible_for_commission": false,
        "region": "US",
        "intelligence_status": "ready",
        "intelligence": {
          "primary_topic": "AI tool tutorial walkthrough",
          "category": "education",
          "content_format": "explainer",
          "narrative_arc": "problem_solution",
          "text_density": "high",
          "panel_texts": ["Problem", "Solution step 1", "Result"],
          "image_count": 3,
          "brand_safety_tier": "safe"
        }
      }
    ]
  }
}

Slideshow items carry the same intelligence_status flag as video items (ready · pending · disabled · failed · skipped) when the parent comet was created with data_intelligence_enabled: true. The intelligence payload shape is different from videos — slideshows analyse per-panel text (panel_texts, panel_text_word_count, narrative_arc, text_density, image_count) instead of a transcript, and drop video-only fields like visual_format, camera_perspective, and scene_changed. See the Data Intelligence reference for the full slideshow schema.

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:Free(included with Comet creation)

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. Each outlier may include an optional weighted_score (Virality Score), sortable via order_by=weighted_score.

Cost per request:Free(included with Comet creation)

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, weighted_score. 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,
        "weighted_score": 26.9,
        "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"]
          }
        ]
      }
    ]
  }
}

GET/v1/comet/:id/analysis

Query comet analyses

Returns every past analysis this comet has produced, ordered newest first. Each item represents one completed collection cycle. Useful for tracking how the AI summary and underlying trends have evolved over time, or feeding external dashboards.

Cost per request:Free(included with Comet creation)

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
limit
Type
integer
Description
Maximum number of analyses to return (1-100). Default is 20.
Name
start_date
Type
string
Description
ISO 8601 date to filter analyses from (inclusive).
Name
end_date
Type
string
Description
ISO 8601 date to filter analyses until (inclusive).

Request

GET

/v1/comet/:id/analysis

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

Response

{
  "data": [
    {
      "id": "f0e6f5e7-fbfd-4545-8481-3129c746e85f",
      "insight_type": "custom_niche",
      "reference_id": "123e4567-e89b-12d3-a456-426614174000",
      "batch_start": "2025-01-08T00:00:00.000Z",
      "batch_end": "2025-01-15T00:00:00.000Z",
      "analysis": "Bootstrapped founders dominated...",
      "analysis_data": { "themes": ["..."], "viral_tactics": ["..."] }
    },
    {
      "id": "9ab37c1e-2b94-4b55-9e12-1a3b4c5d6e7f",
      "insight_type": "custom_niche",
      "reference_id": "123e4567-e89b-12d3-a456-426614174000",
      "batch_start": "2025-01-01T00:00:00.000Z",
      "batch_end": "2025-01-08T00:00:00.000Z",
      "analysis": "Last week's theme was creator-led product launches...",
      "analysis_data": { "themes": ["..."] }
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 12,
    "has_more": false
  }
}

GET/v1/comet/:id/analysis/latest

Get latest comet analysis

Returns the AI-generated social intelligence analysis for the most recent completed collection cycle of this comet. The analysis runs automatically on every cycle and covers the videos collected in that batch. Each comet cycle produces one analysis record.

Cost per request:Free(included with Comet creation)

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration.

Response fields

Name
id
Type
string
Description
UUID of the analysis record.
Name
insight_type
Type
string
Description
Always "custom_niche" for comet analyses.
Name
reference_id
Type
string
Description
UUID of the comet configuration this analysis belongs to.
Name
batch_start
Type
string
Description
ISO 8601 timestamp marking the start of the batch window analyzed.
Name
batch_end
Type
string
Description
ISO 8601 timestamp marking the end of the batch window analyzed (usually the last_run_at of the cycle).
Name
analysis
Type
string
Description
Short one-sentence narrative summary of what drove engagement in this batch.
Name
analysis_data
Type
object
Description
Full structured analysis including themes (the distinct trends surfaced in this batch), viral_tactics, timing_analysis, and overview. See the Trends endpoint for a flat, paginated projection of the same themes.

Request

GET

/v1/comet/:id/analysis/latest

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

Response

{
  "data": {
    "id": "f0e6f5e7-fbfd-4545-8481-3129c746e85f",
    "insight_type": "custom_niche",
    "reference_id": "123e4567-e89b-12d3-a456-426614174000",
    "batch_start": "2025-01-08T00:00:00.000Z",
    "batch_end": "2025-01-15T00:00:00.000Z",
    "analysis": "Bootstrapped founders dominated this week with unsexy-profitability narratives: waste management, B2B SaaS, and niche product validation drove 80M+ combined views.",
    "analysis_data": {
      "themes": [
        {
          "stable_key": "unsexy-profitability",
          "name": "Unsexy Profitability (Waste Management, B2B, SaaS)",
          "why_it_works": "Reframes success away from vanity brands; audiences crave permission to build boring, scalable businesses.",
          "video_count": 8,
          "evidence_video_ids": ["0c675286-d6e9-413f-9ff5-24138c6e2ff6"],
          "tactics": ["founder-led monologue", "screenshot of revenue dashboard"],
          "confidence": 0.88
        }
      ],
      "viral_tactics": ["..."],
      "timing_analysis": { "peak_hours": [14, 20], "pattern": "..." },
      "overview": { "total_videos": 80, "avg_virality": 4847392 }
    }
  }
}

GET/v1/comet/:id/trends

Query comet trends

Returns every trend record this comet has produced, ordered newest first. Each trend carries its batch_start, batch_end, and stable_key, so you can group by stable_key to reconstruct a time series for a single trend across cycles.

Useful for:

Charting how total_views, video_count, or avg_virality_score for a given stable_key evolves over time
Identifying trends that persist (steady) vs. emerge (new) vs. decay (fading)
Feeding external dashboards or BI tools

Cost per request:Free(included with Comet creation)

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration.

Query parameters

Name
page
Type
integer
Description
Page number for pagination (1-indexed). Default is 1.
Name
limit
Type
integer
Description
Maximum number of trend records to return (1-100). Default is 50.
Name
stable_key
Type
string
Description
Filter to return only trend records matching a specific stable_key. Useful for building single-trend time series.
Name
start_date
Type
string
Description
ISO 8601 date to filter trends from (inclusive).
Name
end_date
Type
string
Description
ISO 8601 date to filter trends until (inclusive).

Response fields (per trend)

Name
rank
Type
integer
Description
1-based rank within this batch (lower = more prominent).
Name
stable_key
Type
string
Description
Slug-like identifier reused by the LLM across cycles. Use it to join the same trend across batches.
Name
name
Type
string
Description
Human-readable name of the trend.
Name
why_it_works
Type
string
Description
Short explanation of why this trend drives engagement.
Name
tactics
Type
string[]
Description
Concrete execution tactics creators use for this trend.
Name
confidence
Type
number
Description
LLM confidence that this is a genuinely distinct trend (0-1).
Name
evidence_video_ids
Type
string[]
Description
UUIDs of videos that constitute the evidence for this trend. Fetch them via GET /v1/comet/:id/videos or the /v1/videos/:id endpoint.
Name
video_count
Type
integer
Description
Number of videos in this trend within the batch.
Name
total_views
Type
integer
Description
Aggregate views across all evidence videos.
Name
total_likes
Type
integer
Description
Aggregate likes across all evidence videos.
Name
total_comments
Type
integer
Description
Aggregate comments across all evidence videos.
Name
total_shares
Type
integer
Description
Aggregate shares across all evidence videos (when reported by the platform).
Name
avg_virality_score
Type
number
Description
Average Virlo virality score across the evidence videos.
Name
platform_breakdown
Type
object
Description
Map of platform → count of evidence videos ({"youtube": 5, "tiktok": 10}).
Name
top_creators
Type
object[]
Description
Top creators contributing to the trend, each with username, platform, and view_contribution.
Name
peak_hour_utc
Type
integer
Description
UTC hour (0-23) when evidence videos were most commonly posted.
Name
status
Type
string
Description
One of new, rising, steady, or fading, compared against the previous batch's trend with the same stable_key.
Name
prev_video_count
Type
integer
Description
Video count the same stable_key had in the previous batch (or null if new).
Name
prev_total_views
Type
integer
Description
Total views the same stable_key had in the previous batch (or null if new).
Name
first_seen_at
Type
string
Description
ISO 8601 timestamp of the batch when this stable_key was first observed.

Trends for historical batches that predate April 22, 2026 were backfilled from the legacy analysis_data.themes object. Those records have name, why_it_works, video_count, and rank populated, but aggregate fields (total_views, platform_breakdown, top_creators, evidence_video_ids, tactics, confidence) are empty because that data was never captured upstream. New cycles produce the full enriched shape.

Request

GET

/v1/comet/:id/trends

curl -G https://api.virlo.ai/v1/comet/123e4567-e89b-12d3-a456-426614174000/trends \
  -H "Authorization: Bearer {token}" \
  -d stable_key=unsexy-profitability \
  -d limit=50

Response

{
  "data": [
    {
      "id": "c7ecb571-fc19-4b9b-b3ff-c95ce85028de",
      "viral_insight_id": "f0e6f5e7-fbfd-4545-8481-3129c746e85f",
      "reference_id": "123e4567-e89b-12d3-a456-426614174000",
      "insight_type": "custom_niche",
      "batch_start": "2025-01-08T00:00:00.000Z",
      "batch_end": "2025-01-15T00:00:00.000Z",
      "rank": 1,
      "stable_key": "unsexy-profitability",
      "name": "Unsexy Profitability",
      "video_count": 8,
      "total_views": 42180000,
      "status": "rising",
      "prev_video_count": 5,
      "prev_total_views": 21500000
    },
    {
      "id": "b1a2c3d4-e5f6-7890-abcd-ef1234567890",
      "viral_insight_id": "9ab37c1e-2b94-4b55-9e12-1a3b4c5d6e7f",
      "reference_id": "123e4567-e89b-12d3-a456-426614174000",
      "insight_type": "custom_niche",
      "batch_start": "2025-01-01T00:00:00.000Z",
      "batch_end": "2025-01-08T00:00:00.000Z",
      "rank": 2,
      "stable_key": "unsexy-profitability",
      "name": "Unsexy Profitability",
      "video_count": 5,
      "total_views": 21500000,
      "status": "new",
      "prev_video_count": null,
      "prev_total_views": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 2,
    "has_more": false
  }
}

GET/v1/comet/:id/trends/latest

Get latest comet trends

Returns the structured trends surfaced in the most recent completed collection cycle, ranked by relevance. Each trend is a cluster of on-topic videos that share the same underlying subject, angle, format, or narrative driver. Trends include evidence videos and aggregate statistics computed directly from those videos.

Each trend also carries a stable_key that the LLM reuses across cycles, plus a status (new, rising, steady, fading) so you can track how a trend evolves week over week.

Cost per request:Free(included with Comet creation)

Path parameters

Name
id
Type
string
Required
*
Description
UUID of the comet configuration.

Request

GET

/v1/comet/:id/trends/latest

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

Response

{
  "data": {
    "reference_id": "123e4567-e89b-12d3-a456-426614174000",
    "insight_type": "custom_niche",
    "viral_insight_id": "f0e6f5e7-fbfd-4545-8481-3129c746e85f",
    "batch_start": "2025-01-08T00:00:00.000Z",
    "batch_end": "2025-01-15T00:00:00.000Z",
    "total": 6,
    "trends": [
      {
        "id": "c7ecb571-fc19-4b9b-b3ff-c95ce85028de",
        "viral_insight_id": "f0e6f5e7-fbfd-4545-8481-3129c746e85f",
        "insight_type": "custom_niche",
        "reference_id": "123e4567-e89b-12d3-a456-426614174000",
        "batch_start": "2025-01-08T00:00:00.000Z",
        "batch_end": "2025-01-15T00:00:00.000Z",
        "rank": 1,
        "stable_key": "unsexy-profitability",
        "name": "Unsexy Profitability (Waste Management, B2B, SaaS)",
        "why_it_works": "Reframes success away from vanity brands; audiences crave permission to build boring, scalable businesses.",
        "tactics": ["founder-led monologue", "screenshot of revenue dashboard", "before/after reveal"],
        "confidence": 0.88,
        "evidence_video_ids": ["0c675286-d6e9-413f-9ff5-24138c6e2ff6", "7606705096256261406"],
        "video_count": 8,
        "total_views": 42180000,
        "total_likes": 1850000,
        "total_comments": 78400,
        "total_shares": 42100,
        "avg_virality_score": 5.27,
        "platform_breakdown": { "youtube": 5, "tiktok": 3 },
        "top_creators": [
          { "username": "founders_lab", "platform": "tiktok", "view_contribution": 18200000 }
        ],
        "peak_hour_utc": 14,
        "status": "rising",
        "first_seen_at": "2024-12-25T00:00:00.000Z",
        "prev_video_count": 5,
        "prev_total_views": 21500000,
        "created_at": "2025-01-15T01:51:31.279Z"
      }
    ]
  }
}

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 slideshows: GET /v1/comet/:id/slideshows to access all collected slideshows (image carousels) 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
Read the AI analysis: GET /v1/comet/:id/analysis/latest for the latest cycle's social intelligence report, or /v1/comet/:id/analysis for every past cycle with pagination
Read structured trends: GET /v1/comet/:id/trends/latest for the trends surfaced in the latest cycle with evidence videos and aggregate stats, or /v1/comet/:id/trends?stable_key=... to build a time series for a single trend
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 and slideshows matching your criteria and makes them available through the videos and slideshows endpoints respectively. 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.