Virlo

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:

Maximum of 1000 total results accessible via pagination.

Common Query Parameters

Many video-related endpoints support these filters:

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
    }
  ]
}

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"
          }
        }
      ]
    }
  ]
}

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

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

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

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

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

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)