# Hashtags

> The most-used and most-viewed hashtags in short-form video for any period of up to 90 days, plus video count, views, likes and comments for a single hashtag.

Source: https://dev.virlo.ai/docs/hashtags
Markdown: https://dev.virlo.ai/docs/hashtags.md
Section: Explore data

## About the Virlo API (applies to every page)

- Base URL: `https://api.virlo.ai/v1`. Every request needs the header `Authorization: Bearer YOUR_API_KEY` (keys start with `virlo_tkn_`).
- Responses are JSON inside a `data` field, except the `/v1/webhooks` endpoints, which return the object or array directly. Field names are snake_case.
- Prices are in US dollars from a prepaid balance. 1 credit = $0.01. The `X-Cost` response header on each successful response is the exact charge. Errors are free.
- Slow jobs return an ID. Check its status every 15 seconds (or whatever `retry_after_seconds` says) until `finalized` is `true`.
- All docs pages: https://dev.virlo.ai/llms.txt. Every page in one file: https://dev.virlo.ai/llms-full.txt. MCP server for AI assistants: https://dev.virlo.ai/api/mcp/mcp.

---

See which hashtags short-form videos used most between two dates, or one hashtag's numbers. Answers take seconds.

**At a glance**

- **What it does:** Ranks hashtags across the TikTok, YouTube Shorts and Instagram Reels videos Virlo collects, or sums up one hashtag.
- **You send:** For the top list: a start and end date, at most 90 days apart. For one hashtag: the hashtag, with optional dates.
- **You get back:** Up to 100 hashtags with video counts and total views. Or one hashtag's total and average views, likes and comments.
- **Cost:** $0.05 per successful request, even an empty list. Errors are free.

> **Note:** **What the numbers mean.** `count` is how many videos in Virlo's data used the hashtag and were posted in your dates (UTC, both days included). It is not the platform's own total. `total_views` is those videos' combined views. Stats refresh every 6 hours. Views freeze about a week after posting. Videos Virlo finds after that week are never counted.

---

## Top hashtags for a date range

**Endpoint:** `GET https://api.virlo.ai/v1/hashtags`

The list isn't limited to one niche, so broad tags like `fyp` lead. For hashtags inside one niche, use a [Content Research Agent](https://dev.virlo.ai/docs/agents#get-agent-hashtags).

Cost per request: $0.05

- `start_date` (string, required): Earliest post date, as `YYYY-MM-DD`. Stats start June 1, 2024; ranges before that come back empty.
- `end_date` (string, required): Latest post date, included. At most 90 days after `start_date`: April 1 to June 30 works.
- `limit` (number, optional): How many hashtags: 1 to 100, default 50. Above 100 returns 100. No page 2: `page` repeats the list and charges again.
- `order_by` (string, optional): `count` (default) or `views`.
- `sort` (string, optional): `desc` (default) or `asc`.

**cURL request:**

```bash
curl -G https://api.virlo.ai/v1/hashtags \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d start_date=2026-04-01 \
  -d end_date=2026-06-30 \
  -d order_by=views
```

**JavaScript request:**

```js
const params = new URLSearchParams({
  start_date: '2026-04-01',
  end_date: '2026-06-30',
  order_by: 'views',
})

const res = await fetch(`https://api.virlo.ai/v1/hashtags?${params}`, {
  headers: { Authorization: 'Bearer YOUR_API_KEY' },
})
const { data } = await res.json()
```

**Python request:**

```python
import requests

res = requests.get(
    'https://api.virlo.ai/v1/hashtags',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'start_date': '2026-04-01', 'end_date': '2026-06-30', 'order_by': 'views'},
)
data = res.json()['data']
```

**Response 200:**

```json
{
  "data": [
    { "hashtag": "fyp", "count": 134222, "total_views": 33504743144 },
    { "hashtag": "shorts", "count": 130485, "total_views": 14703578435 },
    { "hashtag": "viral", "count": 73151, "total_views": 14453567398 }
  ]
}
```

**Response 400:**

```json
{
  "statusCode": 400,
  "code": "invalid_date_range",
  "error": "Bad Request",
  "message": "Date range cannot exceed 90 days (91 days provided)"
}
```

---

## One hashtag's performance

**Endpoint:** `GET https://api.virlo.ai/v1/hashtags/:hashtag/performance`

Totals and averages for one hashtag, all platforms combined. It works for hashtags outside the top 100.

Cost per request: $0.05

- `hashtag` (string, required): In the URL, with no `#`. Case doesn't matter. A typed `#` breaks the URL and returns `start_date must be a string`; write `%23` if needed.
- `start_date` (string, optional): Optional, as `YYYY-MM-DD`. Without `end_date`, you get that day to today.
- `end_date` (string, optional): Optional. Without `start_date`: everything up to that day. Leave both out for all-time totals. With both: at most 90 days apart.

**cURL request:**

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

**JavaScript request:**

```js
const params = new URLSearchParams({
  start_date: '2026-04-01',
  end_date: '2026-06-30',
})

const res = await fetch(
  `https://api.virlo.ai/v1/hashtags/fyp/performance?${params}`,
  { headers: { Authorization: 'Bearer YOUR_API_KEY' } },
)
const { data } = await res.json()
```

**Python request:**

```python
import requests

res = requests.get(
    'https://api.virlo.ai/v1/hashtags/fyp/performance',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    params={'start_date': '2026-04-01', 'end_date': '2026-06-30'},
)
data = res.json()['data']
```

**Response 200:**

```json
{
  "data": {
    "hashtag": "fyp",
    "video_count": 134222,
    "total_views": 33504743144,
    "avg_views": 249621.84,
    "total_likes": 3308657742,
    "avg_likes": 24650.64,
    "total_comments": 26521561,
    "avg_comments": 197.59
  }
}
```

**Response 404:**

```json
{
  "statusCode": 404,
  "code": "not_found",
  "error": "Not Found",
  "message": "No videos found with hashtag: notarealtag123"
}
```

`video_count` is the top list's `count` for the same dates.

---

## Results for one platform

There is no `platform` parameter. For one platform's top list, call `/v1/youtube/hashtags`, `/v1/tiktok/hashtags` or `/v1/instagram/hashtags`. Same parameters, same price.

For one hashtag on one platform:

- **That platform's top list**, if the hashtag is in its top 100. You get only count and views.
- **A [Hashtag lookup](https://dev.virlo.ai/docs/satellite/hashtags)**: fresh videos, top creators and momentum. $0.50, or up to $2.50 with every option. You get a job ID; results take 15 seconds to a few minutes.
- **A [Content Research Agent](https://dev.virlo.ai/docs/agents#get-agent-hashtags)** set to that platform. It collects videos (from $0.50, usually under 20 minutes), then reading its hashtags is free.

The last two count different videos, so numbers won't match this page.

---

## Errors

- `400 Bad Request`: A date isn't `YYYY-MM-DD`, the start is after the end, or the dates are over 90 days apart. On the top list, also a missing date (the message names it), a bad `order_by` or `sort`, or `limit` below 1. Or an unsupported parameter like `platform` or `offset`.
- `401 Unauthorized`: The API key is missing or invalid.
- `402 Payment Required`: Your balance is too low. [Add funds](https://dev.virlo.ai/dashboard/billing).
- `404 Not Found`: One hashtag only: none of the counted videos used it in your dates.
- `429 Too Many Requests`: Over 50 requests a minute, 500 an hour or 5,000 a day on one endpoint. Wait `retry_after` seconds. See [Rate limits](https://dev.virlo.ai/docs/rate-limits).
- `500 Internal Server Error`: An impossible date, such as `2026-02-30`, returns a `500` for now. Fix the date and retry.

See also [Errors](https://dev.virlo.ai/docs/errors).

---

More in Explore data:

- [Trends](https://dev.virlo.ai/docs/trends.md)
- [Sounds](https://dev.virlo.ai/docs/sounds.md)
- [Hooks](https://dev.virlo.ai/docs/hooks.md)
- [Videos](https://dev.virlo.ai/docs/videos.md)