Virlo Short-Form Video Training Data

Virlo

Social media intelligence for short-form video — Bloomberg for viral content.

Homepage: https://dev.virlo.ai Source: https://github.com/CalciferFriend/virlo-skill Full API docs: https://dev.virlo.ai/docs | Playground: https://dev.virlo.ai/docs/playground

Config

Set VIRLO_API_KEY environment variable. Your API key has the format virlo_tkn_ and can be obtained from the Virlo dashboard.

Context

The Virlo API provides cross-platform analytics across YouTube, TikTok, and Instagram. Key capabilities:

API Access

All endpoints use base URL https://api.virlo.ai/v1, snake_case naming, and return data in a { "data": ... } envelope.

Making Requests

Use curl directly with the VIRLO_API_KEY environment variable:

# GET request
curl -s -X GET "https://api.virlo.ai" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
POST request with JSON body
curl -s -X POST "https://api.virlo.ai" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d ''

Examples

# List top hashtags
curl -s -X GET "https://api.virlo.ai/v1/hashtags" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Top 10 viral videos
curl -s -X GET "https://api.virlo.ai/v1/videos?limit=10" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Daily trend digest
curl -s -X GET "https://api.virlo.ai/v1/trends" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Create an Orbit search
curl -s -X POST "https://api.virlo.ai/v1/orbit" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI research","keywords":["artificial intelligence","AI tools"]}'

API Reference

Authentication

All requests require a Bearer token:

Authorization: Bearer virlo_tkn_

Never commit API keys to version control. Regenerate compromised keys from the dashboard.

Response Envelope

All responses use a { "data": ... } envelope. List endpoints include pagination metadata:

{
  "data": {
    "total": 500,
    "limit": 50,
    "offset": 0,
    "items": [ ... ]
  }
}

Pagination

List endpoints use offset-based pagination via limit and page query parameters:

| Parameter | Type | Default | Description | | --------- | ------- | ------- | ----------------------- | | limit | integer | 50 | Items per page (1-100) | | page | integer | 1 | Page number (1-indexed) |

Maximum of 1000 total results accessible via pagination.

Common Query Parameters

Many video-related endpoints support these filters:

| Parameter | Type | Description | | ------------ | ------- | ------------------------------------------------- | | min_views | integer | Minimum view count threshold | | platforms | string | Comma-separated: youtube, tiktok, instagram | | start_date | string | ISO 8601 date filter (earliest publish date) | | end_date | string | ISO 8601 date filter (latest publish date) | | order_by | string | Sort field (varies per endpoint) | | sort | string | Sort direction: asc or desc (default: desc) |

Platforms

Hashtags

Virlo tracks 500K+ hashtags ranked by usage count and total views.

#### List Hashtags

GET /v1/hashtags

Standard pagination (limit, page).

Response:

{
  "data": [
    {
      "hashtag": "#shorts",
      "count": 10926,
      "total_views": 869912593
    }
  ]
}

| Field | Type | Description | | ------------- | ------- | --------------------------------------------- | | hashtag | string | The hashtag text (may or may not include #) | | count | integer | Number of videos using this hashtag | | total_views | integer | Sum of views across all videos with this tag |

Trends

Daily curated trending topics updated at 1am UTC.

#### List Trend Groups

GET /v1/trends

Standard pagination (limit, page).

Response:

{
  "data": [
    {
      "id": "b88c0c23-8501-4975-a1e9-b7c1160c6342",
      "title": "Trends for Oct 15th",
      "trends": [
        {
          "id": "132ea402-804d-4515-b706-f3ff9c698c5e",
          "trend_id": "8ab75d1a-cb50-4885-b9b3-2e4ede2a3620",
          "trend_group_id": "b88c0c23-8501-4975-a1e9-b7c1160c6342",
          "ranking": 1,
          "trend": {
            "id": "8ab75d1a-cb50-4885-b9b3-2e4ede2a3620",
            "name": "NBA Season Opening Night",
            "description": "The 2025-26 NBA season officially tipped off...",
            "trend_type": "content"
          }
        }
      ]
    }
  ]
}

| Field | Type | Description | | -------- | ------ | ------------------------------------------------ | | id | string | UUID of the trend group | | title | string | Display title (e.g., "Trends for Oct 15th") | | trends | array | Array of ranked trend entries |

Trend entry fields: id, trend_id, trend_group_id, ranking, trend (object with id, name, description, trend_type).

Videos

2M+ viral videos across YouTube, TikTok, and Instagram.

#### List Top Videos (Cross-Platform)

GET /v1/videos

| Parameter | Type | Description | | ------------ | ------- | ------------------------------------------------- | | limit | integer | Items per page (1-100, default 50) | | page | integer | Page number (1-indexed, default 1) | | min_views | integer | Minimum view count filter | | platforms | string | Comma-separated: youtube, tiktok, instagram | | start_date | string | ISO 8601 earliest publish date | | end_date | string | ISO 8601 latest publish date | | order_by | string | publish_date, views, created_at | | sort | string | asc or desc (default: desc) |

#### Platform-Specific Endpoints

GET /v1/youtube-videos
GET /v1/tiktok-videos
GET /v1/instagram-videos

Same parameters and response shape as /v1/videos, filtered to a single platform.

#### Video Object Fields

| Field | Type | Description | | -------------------- | ------------ | ------------------------------------------ | | id | string | Virlo UUID | | url | string | Original video URL | | publish_date | string | ISO 8601 publish timestamp | | views | integer | View count | | number_of_likes | integer | Like count | | number_of_comments | integer | Comment count | | description | string | Video description | | thumbnail_url | string | Thumbnail image URL | | hashtags | string[] | Extracted hashtags | | type | string | Platform: youtube, tiktok, instagram | | niche | string | Content niche category | | author_id | string | UUID of the video author | | bookmarks | integer | Bookmark/save count | | external_id | string | Platform-specific video ID | | region | string/null | Geographic region code | | duration | integer | Duration in seconds | | transcript_raw | string/null | Raw video transcript (when available) |

Orbit — Social Listening

Queue keyword-based video discovery jobs that search across platforms. Supports async analysis, Meta ads collection, and creator outlier detection.

#### Create Orbit Search

POST /v1/orbit

| Field | Type | Required | Description | | ------------------------- | -------- | -------- | -------------------------------------------------------------- | | name | string | Yes | Descriptive name for the search job | | keywords | string[] | Yes | Keywords to search (1-10) | | platforms | string[] | No | Platforms: youtube, tiktok, instagram. Default: all | | min_views | integer | No | Minimum view count threshold | | time_period | string | No | today, this_week, this_month, this_year | | run_analysis | boolean | No | Enable AI social intelligence analysis (default: false) | | enable_meta_ads | boolean | No | Enable Meta ads collection (default: false) | | exclude_keywords | string[] | No | Keywords to exclude from results | | exclude_keywords_strict | boolean | No | Also check transcripts for exclusions (default: false) |

#### List Orbit Searches

GET /v1/orbit

Paginated list of all search jobs. Standard limit/page parameters.

#### Get Orbit Results

GET /v1/orbit/:orbit_id

Poll until job completes. When run_analysis: true, includes AI analysis report.

Query params: order_by (views, likes, shares, comments, bookmarks, publish_date, author.followers), sort (asc/desc).

Response fields: name, keywords, analysis (markdown AI report when ready), results (contains total_videos, platform counts, trends, videos, ads, creators).

#### Get Orbit Videos (Paginated)

GET /v1/orbit/:orbit_id/videos

Standard pagination plus min_views, platforms, start_date, end_date, order_by, sort.

#### Get Orbit Ads

GET /v1/orbit/:orbit_id/ads

Meta ads collected (requires enable_meta_ads: true). Pagination plus order_by (created_at, page_like_count), sort.

#### Get Creator Outliers

GET /v1/orbit/:orbit_id/creators/outliers

Creators outperforming their follower count. High outlier_ratio = content reaching far beyond follower base. Standard pagination.

Comet — Automated Niche Monitoring

Create niche configs that automatically discover videos, ads, and creator outliers on a schedule.

#### Create Comet Config

POST /v1/comet

| Field | Type | Required | Description | | ------------------------- | -------- | -------- | ------------------------------------------------------ | | name | string | Yes | Descriptive name (e.g., "Tech Reviews") | | keywords | string[] | Yes | Keywords to search (1-20) | | platforms | string[] | Yes | Platforms: youtube, tiktok, instagram | | cadence | string | Yes | daily, weekly, monthly, or cron expression | | min_views | integer | Yes | Minimum view count threshold | | time_range | string | Yes | today, this_week, this_month, this_year | | is_active | boolean | No | Default: true. Set false to create paused | | meta_ads_enabled | boolean | No | Enable Meta ads collection (default: false) | | exclude_keywords | string[] | No | Keywords to exclude | | exclude_keywords_strict | boolean | No | Also check transcripts for exclusions (default: false) |

#### List Comet Configs

GET /v1/comet

Add ?include_inactive=true to include deactivated configs.

#### Get / Update / Delete Comet Config

GET /v1/comet/:id
PUT /v1/comet/:id       # Full replacement — all required fields must be provided
DELETE /v1/comet/:id     # Soft-delete, returns 204

#### Get Comet Videos

GET /v1/comet/:id/videos

Standard pagination plus min_views, platforms, start_date, end_date, order_by, sort.

#### Get Comet Ads

GET /v1/comet/:id/ads

Requires meta_ads_enabled: true. Standard pagination plus order_by (created_at, page_like_count), sort.

#### Get Creator Outliers

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

Standard pagination.

Error Handling

| Code | Name | Description | | ---- | --------------------- | ------------------------------------- | | 200 | OK | Request processed successfully | | 201 | Created | Resource created | | 202 | Accepted | Async job queued (e.g., Orbit search) | | 204 | No Content | Successful deletion | | 400 | Bad Request | Invalid request parameters | | 401 | Unauthorized | Missing or invalid API key | | 403 | Forbidden | Insufficient permissions | | 404 | Not Found | Resource not found | | 422 | Unprocessable Entity | Valid syntax but cannot process | | 429 | Too Many Requests | Rate limit exceeded | | 500 | Internal Server Error | Server error |

Error response format:

{
  "error": {
    "type": "validation_error",
    "message": "keywords is required",
    "param": "keywords"
  }
}

Rate Limits

# List top hashtags
curl -s -X GET "https://api.virlo.ai/v1/hashtags" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Top 10 viral videos
curl -s -X GET "https://api.virlo.ai/v1/videos?limit=10" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Daily trend digest
curl -s -X GET "https://api.virlo.ai/v1/trends" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json"
Create an Orbit search
curl -s -X POST "https://api.virlo.ai/v1/orbit" \
  -H "Authorization: Bearer ${VIRLO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"AI research","keywords":["artificial intelligence","AI tools"]}'

Set VIRLO_API_KEY environment variable. Your API key has the format virlo_tkn_ and can be obtained from the Virlo dashboard.