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_<your_key> and can be obtained from the Virlo dashboard.

Context

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

Hashtags — 500K+ hashtags ranked by usage count and total views
Trends — Daily curated trending topics updated at 1am UTC
Videos — 2M+ viral video performance data (views, likes, shares, comments)
Orbit — Keyword-based social listening with async analysis jobs
Comet — Automated niche monitoring with scheduled scraping

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<endpoint>" 
  -H "Authorization: Bearer ${VIRLO_API_KEY}" 
  -H "Content-Type: application/json"

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

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_<your_key>

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

youtube — YouTube Shorts and videos
tiktok — TikTok videos
instagram — Instagram Reels

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)

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

Max limit per request: 100 items
Max total accessible results: 1,000 items per query
On 429, back off and retry after the retry_after value (in seconds)

virlo-short-form-video-training-data

Installation

Virlo

Config

Context

API Access

Making Requests

Examples

API Reference

Authentication

Response Envelope

Common Query Parameters

Platforms

Hashtags

List Hashtags

Trends

List Trend Groups

Videos

List Top Videos (Cross-Platform)

Platform-Specific Endpoints

Video Object Fields

Create Orbit Search

List Orbit Searches

Get Orbit Results

Get Orbit Videos (Paginated)

Get Orbit Ads

Get Creator Outliers

Comet — Automated Niche Monitoring

Create Comet Config

List Comet Configs

Get / Update / Delete Comet Config

Get Comet Videos

Get Comet Ads

Get Creator Outliers

Error Handling

Rate Limits

virlo-short-form-video-training-data

Installation

Virlo

Config

Context

API Access

Making Requests

Examples

API Reference

Authentication

Response Envelope

Pagination

Common Query Parameters

Platforms

Hashtags

List Hashtags

Trends

List Trend Groups

Videos

List Top Videos (Cross-Platform)

Platform-Specific Endpoints

Video Object Fields

Orbit — Social Listening

Create Orbit Search

List Orbit Searches

Get Orbit Results

Get Orbit Videos (Paginated)

Get Orbit Ads

Get Creator Outliers

Comet — Automated Niche Monitoring

Create Comet Config

List Comet Configs

Get / Update / Delete Comet Config

Get Comet Videos

Get Comet Ads

Get Creator Outliers

Error Handling

Rate Limits