Comet

Get creator outliers for a comet configuration

Retrieves creators who significantly outperform their follower count. Every row uses one canonical shape (V1OutlierItemDto). With order_by=rising (Phase 3) rows are ranked by true run-over-run velocity and carry additive growth_followers / growth_views / growth_video_count / local_video_count fields, while the outlier-only metrics (avg_views, outlier_ratio, creator_topics, identified_at) come back null/empty. On a young Comet without two snapshots, rising transparently falls back to the weighted-outlier ranking. Because the velocity snapshots carry no topic data, combining order_by=rising with category uses the topic-aware weighted ranking so the filter is honored (ranking: "outlier_fallback"). Each row carries an author_id — pass it as :creator_id to GET /v1/comet/:id/creators/:creator_id/similar to find adjacent creators.

get/v1/comet/{id}/creators/outliers

Request

  • Base URL: https://api.virlo.ai
  • URL: https://api.virlo.ai/v1/comet/{id}/creators/outliers
  • Auth: HTTP bearer

Path parameters

idstring required

UUID of the comet configuration

Query parameters

limitnumber
Example:50

Maximum number of items to return. Values above 100 are clamped to 100 rather than rejected.

pagenumber
Example:1

Page number for pagination

order_by'outlier_ratio' | 'avg_views' | 'follower_count' | 'weighted_score' | 'rising'
Example:outlier_ratio

Field to sort by. rising (Phase 3) ranks creators by true run-over-run velocity (follower/view growth in the niche) using per-run snapshots; on a young Comet with sparse snapshots it transparently falls back to the weighted outlier ranking.

sort'asc' | 'desc'
Example:desc

Sort direction

platform'youtube' | 'tiktok' | 'instagram'

Filter by platform

follower_tier'nano' | 'micro' | 'mid' | 'macro'

Phase 3: filter to creators in a follower tier. nano (<10K), micro (10K–100K), mid (100K–1M), macro (>1M).

categorystring

Phase 3: case-insensitive substring filter on a creator's matching/creator topics (e.g. "house" within an electronic-music genre Comet).

Response

Successfully retrieved creator outliers

Example response

{
  "data": {
    "comet_id": "550e8400-e29b-41d4-a716-446655440000",
    "total": 15,
    "limit": 50,
    "outliers": [
      {
        "author_id": "a1b2c3d4-5e6f-7890-abcd-ef1234567890",
        "creator_url": "https://www.tiktok.com/@creator",
        "creator_avatar_url": "https://storage.example.com/avatars/abc.jpg",
        "follower_count": 50000,
        "avg_views": 250000,
        "outlier_ratio": 5,
        "weighted_score": 26.9,
        "videos_analyzed": 20,
        "creator_topics": [
          "fitness",
          "health"
        ],
        "matching_topics": [
          "fitness"
        ],
        "platform": "tiktok",
        "identified_at": "2026-01-20T15:00:00.000Z",
        "median_views": 180000,
        "top_video_views": 990000,
        "breakout_video_count": 7,
        "avg_engagement_rate": 0.0842,
        "posts_per_week": 4.5,
        "content_angle": "Turns dry insurance topics into fast, myth-busting explainers with a strong first-line hook.",
        "growth_followers": 1200,
        "growth_views": 450000,
        "growth_video_count": 4,
        "local_video_count": 12,
        "videos": [
          {
            "id": "550e8400-e29b-41d4-a716-446655440000",
            "title": "How I grew to 100k followers",
            "description": "Full description of the video",
            "views": 250000,
            "likes": 12000,
            "comments": 340,
            "publish_date": "2026-01-15T10:30:00.000Z",
            "publishDate": "2026-01-15T10:30:00.000Z",
            "url": "https://www.tiktok.com/@user/video/123",
            "hashtags": [
              "fyp",
              "viral"
            ],
            "thumbnail_url": "https://storage.example.com/thumbnails/abc.jpg",
            "type": "tiktok"
          }
        ]
      }
    ]
  }
}

Changes

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