Hashtags

Retrieve hashtag analytics — popularity, usage counts, and total views. Each request costs $0.05.

Pass hashtags without # (e.g. fyp, not #fyp). Leading # is stripped, and #tag / tag are treated as the same key in rankings and performance.

Platform-specific paths

The hashtag list endpoint is available per platform, with identical parameters and response shape:

Platform	List
Cross-platform	`GET /v1/hashtags`
YouTube	`GET /v1/youtube/hashtags`
TikTok	`GET /v1/tiktok/hashtags`
Instagram	`GET /v1/instagram/hashtags`

Performance is cross-platform only. GET /v1/hashtags/:hashtag/performance aggregates across every platform; there is no per-platform performance route. To compare a hashtag's performance on one platform, use the per-platform list endpoints above, or a Content Research Agent with platforms set and read GET /v1/agents/:id/hashtags, which reports per-hashtag analytics scoped to that agent's platform set.

GET/v1/hashtags

Get hashtags

Returns hashtag statistics for a date range, with flexible sorting. start_date and end_date are required and the window cannot exceed 90 days — a wider range returns 400.

Cost per request:$0.05

Query parameters

Name
start_date
Type
string
Required
*
Description
Start date for filtering (YYYY-MM-DD format). Required.
Name
end_date
Type
string
Required
*
Description
End date for filtering (YYYY-MM-DD format, maximum 90 days from start_date). Required.
Name
limit
Type
number
Description
Maximum number of results (1-100). Default is 50.
Name
order_by
Type
string
Description
Field to sort by: count or views. Default is count.
Name
sort
Type
string
Description
Sort direction: asc or desc. Default is desc.

Request

GET

/v1/hashtags

curl -G https://api.virlo.ai/v1/hashtags \
  -H "Authorization: Bearer {token}" \
  -d start_date=2026-04-01 \
  -d end_date=2026-06-30 \
  -d limit=50 \
  -d order_by=views \
  -d sort=desc

Response

{
  "data": [
    {
      "hashtag": "#shorts",
      "count": 10926,
      "total_views": 869912593
    },
    {
      "hashtag": "fyp",
      "count": 7526,
      "total_views": 2373785394
    },
    {
      "hashtag": "#funny",
      "count": 3616,
      "total_views": 274258005
    }
  ]
}

GET/v1/hashtags/:hashtag/performance

Get hashtag performance

Returns aggregated performance metrics (views, likes, comments) for videos containing the specified hashtag. This endpoint provides deeper analytics for individual hashtags, including video counts and engagement averages. Optionally filter by date range (maximum 90 days).

Cost per request:$0.05

Path parameters

Name
hashtag
Type
string
Required
*
Description
The hashtag to analyze (without # symbol). Example: fyp or tech

Query parameters

Name
start_date
Type
string
Description
Start date for filtering videos (YYYY-MM-DD format). Optional.
Name
end_date
Type
string
Description
End date for filtering videos (YYYY-MM-DD format). Optional. If both dates provided, maximum 90 days range.

Request

GET

/v1/hashtags/:hashtag/performance

curl -G https://api.virlo.ai/v1/hashtags/fyp/performance \
  -H "Authorization: Bearer {token}" \
  -d start_date=2026-04-01 \
  -d end_date=2026-06-30

Response

{
  "data": {
    "hashtag": "fyp",
    "video_count": 206,
    "total_views": 1136934142,
    "avg_views": 5519097.78,
    "total_likes": 96546584,
    "avg_likes": 468672.74,
    "total_comments": 866458,
    "avg_comments": 4206.11
  }
}

Error responses

The hashtags endpoints may return the following error codes:

Name
400 Bad Request
Description
Invalid parameters provided. Common causes include: - Invalid date format (must be YYYY-MM-DD) - Both start_date and end_date are required for /v1/hashtags endpoint - Date range exceeds 90 days - Invalid order_by value (must be 'count' or 'views') - Invalid sort value (must be 'asc' or 'desc') - Empty hashtag parameter
Name
401 Unauthorized
Description
Missing or invalid API key. Ensure you're including your API key in the Authorization header.
Name
402 Payment Required
Description
Insufficient prepaid balance. Add funds at dev.virlo.ai/dashboard/billing.
Name
404 Not Found
Description
(Performance endpoint only) No videos found with the specified hashtag in the database or date range.
Name
429 Too Many Requests
Description
Rate limit exceeded. Your plan has specific rate limits per endpoint. Wait before making additional requests.