virlo

name	virlo
description	Virlo social media intelligence — viral video analytics, hashtag rankings, trend digests, and social listening across YouTube, TikTok, and Instagram. Use for content strategy, trend discovery, competitive analysis, and niche monitoring.
license	MIT
metadata	{"openclaw":{"emoji":"☄️","requires":{"bins":"[Truncated]","env":"[Truncated]"},"primaryEnv":"VIRLO_API_KEY","homepage":"https://dev.virlo.ai","source":"https://github.com/CalciferFriend/virlo-skill"}}

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)

---

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

• 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)