# Hashtag

Schemas

Public hashtags with their description, image and how many posts carry them (and, where shown, their views).

## Endpoints

4 endpoints return hashtags on Instagram and TikTok.

- [GETInstagram Hashtag API`/v1/instagram/hashtag`](https://socialtap.dev/docs/reference/instagram/hashtag/index.md)
- [GETInstagram Hashtag Search API`/v1/instagram/search_hashtags`](https://socialtap.dev/docs/reference/instagram/search_hashtags/index.md)
- [GETTikTok Hashtag API`/v1/tiktok/hashtag`](https://socialtap.dev/docs/reference/tiktok/hashtag/index.md)
- [GETTikTok Trending Hashtags API`/v1/tiktok/trending_hashtags`](https://socialtap.dev/docs/reference/tiktok/trending_hashtags/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (tiktok, instagram, …). |
| `id` | `string` | Platform-native hashtag ID (TikTok's challenge ID, Threads' tag ID); on platforms whose public pages key a hashtag by its name (Instagram, YouTube, Facebook, X), the name lowercased. |
| `name` | `string` | The tag without #, as the platform shows it (case kept). Threads tags may contain spaces ("book club"). |
| `url` | `string` (uri) | Canonical hashtag page URL (for a multi-word Threads tag, its tag search page). |
| `description` | `string` or `null` | The hashtag's description as its page shows it; null when it has none. |
| `thumbnail_url` | `string` (uri) or `null` | The hashtag's own picture (not one of its posts' images); null when it has none. Platform CDN URLs can expire. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.post_count` | `integer` or `null` | Posts carrying the tag, as the platform counts them; rounded on YouTube and Threads (see approximate_fields). |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.tiktok` | `object` or `null` | A TikTok hashtag's own fields. |
| `platform_specific.tiktok.view_count` | `integer` or `null` | Views across every post carrying the tag, all time, exact; null where TikTok does not show it. |
| `platform_specific.tiktok.banner_url` | `string` (uri) or `null` | The hashtag page's cover image URL; null when it has none. TikTok CDN URLs can expire. |
| `platform_specific.tiktok.is_promoted` | `boolean` or `null` | An advertiser's hashtag: a Branded Hashtag Challenge, or one Creative Center marks promoted. |
| `platform_specific.tiktok.rank` | `integer` or `null` | Position on the requested trending board (1 = most popular; the request's country, period and industry); null off a board. |
| `platform_specific.tiktok.rank_change` | `integer` or `null` | Places climbed since the previous period (negative: fell, 0: unchanged); null when new to the board or off a board. |
| `platform_specific.tiktok.is_new_to_board` | `boolean` or `null` | First time on the board this period; null off a board. |
| `platform_specific.tiktok.period_post_count` | `integer` or `null` | Posts with the tag published in the board's period (the request's window); null off a board. |
| `platform_specific.tiktok.period_view_count` | `integer` or `null` | Views in the board's period of posts with the tag; null off a board. |
| `platform_specific.tiktok.industry` | `string` or `null` | The industry Creative Center files the hashtag under (Apparel & Accessories, Games, …), as shown; not normalized. |
| `platform_specific.tiktok.trend` | `object[]` | The hashtag's popularity over the board's period, oldest first; \[\] off a board (in unknown_fields). |
| `platform_specific.tiktok.trend[].start_at` | `string` (date-time) | Start of the interval (a day on TikTok's boards), RFC 3339 UTC. |
| `platform_specific.tiktok.trend[].popularity` | `number` | Popularity in the interval relative to the period's peak, 0 to 1, as Creative Center scales it. |
| `platform_specific.instagram` | `object` or `null` | An Instagram hashtag's own fields. |
| `platform_specific.instagram.is_restricted` | `boolean` or `null` | Instagram restricts the tag: its posts are hidden (a tag it reports as sensitive), though it exists. |
| `platform_specific.instagram.is_trending` | `boolean` or `null` | Instagram marks the tag trending; null where it does not say (search results). |
| `platform_specific.instagram.tag_id` | `string` or `null` | Instagram's own numeric ID of the hashtag; null where the source does not show it (a tag Instagram withholds). |
| `platform_specific.youtube` | `object` or `null` | A YouTube hashtag's own fields. |
| `platform_specific.youtube.channel_count` | `integer` or `null` | Channels that posted with the tag, rounded by YouTube (in approximate_fields). |
| `platform_specific.threads` | `object` or `null` | A Threads tag's own fields. |
| `platform_specific.threads.is_community` | `boolean` or `null` | The tag is a Threads community ("NBA Threads"), not a plain tag. |
| `platform_specific.threads.recent_post_count` | `integer` or `null` | Recent posts with the tag as Threads counts them (it does not state the window), rounded (in approximate_fields). |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("36M videos": metrics.post_count). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, hashtag endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/hashtag/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)