# Hashtag Analysis

The Hashtag Analysis endpoints help you understand how hashtags perform across your workspace or a specific account. Use them to rank, filter, and retrieve top posts for any hashtag.

### Requirements

**Authentication:** Bearer API token\
**Scope:** `analytics`\
**Headers:**

* `Authorization: Bearer-API YOUR_API_KEY`
* `Publer-Workspace-Id: YOUR_WORKSPACE_ID`

### Endpoints

### 1. Get Hashtag Insights

Retrieve aggregated analytics for hashtags used in published posts. Supports filtering by date range, account, member, and search, plus sorting and pagination.

```http
GET /api/v1/analytics/:account_id/hashtag_insights
```

#### Description

Returns a paginated list of hashtags with totals for posts, reach, engagement, and related metrics, plus up to 3 recent posts per hashtag and a hashtag performance score.

#### URL Parameter

<table><thead><tr><th width="124.36590576171875">Parameter</th><th width="94.78668212890625">Type</th><th width="109.900634765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Limit to a single social account. Omit for all workspace accounts.</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="121.57464599609375">Param</th><th width="180.772705078125">Type</th><th width="108.6373291015625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>from</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>Start date (inclusive).</td></tr><tr><td><code>to</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>End date (inclusive).</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>No</td><td>One of: <code>posts</code>, <code>reach</code>, <code>likes</code>, <code>comments</code>, <code>shares</code>, <code>video_views</code>. Default <code>posts</code>.</td></tr><tr><td><code>sort_type</code></td><td>string</td><td>No</td><td><code>ASC</code> or <code>DESC</code>. Default <code>DESC</code>.</td></tr><tr><td><code>page</code></td><td>integer</td><td>No</td><td>Page number (0‑based). Each page contains 10 hashtags. Default <code>0</code>.</td></tr><tr><td><code>query</code></td><td>string</td><td>No</td><td>Case‑insensitive filter by hashtag text.</td></tr><tr><td><code>member_id</code></td><td>string</td><td>No</td><td>Filter hashtags by posts authored/managed by a <a href="/pages/fLMnwbYNZN7q5cTdiMdK">member</a>.</td></tr></tbody></table>

## Get Hashtag Insights

> Retrieves comprehensive analytics data for hashtags used in published posts. Provides metrics like reach, engagement, likes, comments, shares, and video views for each hashtag, along with recent posts using each hashtag and hashtag performance scores.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Endpoints for retrieving analytics data and charts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/analytics/{account_id}/hashtag_insights":{"get":{"summary":"Get Hashtag Insights","description":"Retrieves comprehensive analytics data for hashtags used in published posts. Provides metrics like reach, engagement, likes, comments, shares, and video views for each hashtag, along with recent posts using each hashtag and hashtag performance scores.","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve insights from","required":true},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date","required":false},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for hashtag insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date","required":false},{"schema":{"type":"string","enum":["posts","reach","likes","comments","shares","video_views"]},"name":"sort_by","in":"query","description":"Field to sort hashtag results by. Supports various engagement and performance metrics","required":false},{"schema":{"type":"string","enum":["ASC","DESC"]},"name":"sort_type","in":"query","description":"Sort order direction","required":false},{"schema":{"type":"string"},"name":"account_id","in":"path","description":"Filter hashtags for a specific social media account ID. If omitted, includes all workspace accounts","required":false},{"schema":{"type":"integer","minimum":0},"name":"page","in":"query","description":"Page number for pagination (0-based indexing). Each page contains 10 hashtags","required":false},{"schema":{"type":"string"},"name":"query","in":"query","description":"Search query to filter hashtags by name using case-insensitive matching","required":false},{"schema":{"type":"string"},"name":"member_id","in":"query","description":"Filter hashtags by specific workspace member ID","required":false}],"responses":{"200":{"description":"Hashtag insights data with analytics metrics and pagination information","content":{"application/json":{"schema":{"type":"object","properties":{"records":{"type":"array","description":"Array of hashtags with detailed analytics data","items":{"type":"object","properties":{"hashtag":{"type":"string","description":"The hashtag text (without # symbol)"},"posts":{"type":"integer","description":"Number of posts using this hashtag"},"recent_posts":{"type":"array","description":"Array of recent post objects using this hashtag (up to 3 posts)","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the post"},"text":{"type":"string","description":"Post content text"},"scheduled_at":{"type":"string","format":"date-time","description":"Date and time when post was scheduled/published"}}}},"reach":{"type":"integer","description":"Total reach across all posts using this hashtag"},"likes":{"type":"integer","description":"Total likes across all posts using this hashtag"},"comments":{"type":"integer","description":"Total comments across all posts using this hashtag"},"shares":{"type":"integer","description":"Total shares across all posts using this hashtag"},"engagement":{"type":"integer","description":"Total engagement (likes + comments + shares) across all posts using this hashtag"},"video_views":{"type":"integer","description":"Total video views across all video posts using this hashtag"},"link_clicks":{"type":"integer","description":"Total link clicks across all posts using this hashtag"},"post_clicks":{"type":"integer","description":"Total post clicks across all posts using this hashtag"},"saves":{"type":"integer","description":"Total saves across all posts using this hashtag"},"hashtag_score":{"type":"number","format":"float","description":"Performance score of the hashtag as percentage relative to overall post engagement"}}}},"total":{"type":"integer","description":"Total number of hashtags matching the filter criteria (for pagination)"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied - requires analytics access or paying subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

Fields:

* `records[]`: One row per hashtag.
  * `hashtag`: Text without `#`.
  * `posts`: Number of posts using it.
  * `recent_posts[]`: Up to 3 recent posts `{ id, text, scheduled_at }`.
  * Totals: `reach`, `likes`, `comments`, `shares`, `engagement`, `video_views`, `link_clicks`, `post_clicks`, `saves`.
  * `hashtag_score` (%): Relative performance = (total hashtag engagement / total post engagement) × 100.
* `total`: Total hashtags matching filters.

### 2. Get Hashtag Performing Posts

Retrieve up to 6 top posts that used a specific hashtag, with full per‑post analytics.

```http
GET /api/v1/analytics/hashtag_performing_posts
```

#### URL Parameter

<table><thead><tr><th width="124.36590576171875">Parameter</th><th width="78.0074462890625">Type</th><th width="109.900634765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>account_id</code></td><td>string</td><td>No</td><td>Limit to a single social account. Omit for all workspace accounts.</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="131.52691650390625">Param</th><th width="178.8773193359375">Type</th><th width="110.1763916015625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>hashtag</code></td><td>string</td><td>Yes</td><td>Hashtag to analyze (with <code>#</code>).</td></tr><tr><td><code>from</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>Start date (inclusive).</td></tr><tr><td><code>to</code></td><td>date (YYYY-MM-DD)</td><td>No</td><td>End date (inclusive).</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>No</td><td>One of: <code>scheduled_at</code>, <code>reach</code>, <code>engagement</code>, <code>engagement_rate</code>, <code>click_through_rate</code>, <code>reach_rate</code>, <code>postType</code>, <code>likes</code>, <code>video_views</code>, <code>comments</code>, <code>shares</code>, <code>saves</code>, <code>link_clicks</code>, <code>post_clicks</code>. Default <code>scheduled_at</code>.</td></tr><tr><td><code>sort_type</code></td><td>string</td><td>No</td><td><code>ASC</code> or <code>DESC</code>. Default <code>DESC</code>.</td></tr><tr><td><code>member_id</code></td><td>string</td><td>No</td><td>Filter by post author/manager.</td></tr><tr><td><code>query</code></td><td>string</td><td>No</td><td>Text search in post text/title/link info.</td></tr></tbody></table>

## Get Hashtag Performing Posts

> Retrieves the top performing posts for a specific hashtag. Returns up to 6 posts that used the hashtag, with comprehensive analytics metrics including engagement, reach, likes, comments, shares, and video views.

```json
{"openapi":"3.1.1","info":{"title":"Publer API","version":"1.0.0"},"tags":[{"name":"Analytics","description":"Endpoints for retrieving analytics data and charts"}],"servers":[{"url":"https://app.publer.com/api/v1"}],"security":[{"Bearer":[]}],"components":{"securitySchemes":{},"schemas":{"401ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}},"403ErrorResponse":{"type":"object","properties":{"errors":{"type":"array","description":"List of error messages","items":{"type":"string"}}}}}},"paths":{"/analytics/{account_id}/hashtag_performing_posts":{"get":{"summary":"Get Hashtag Performing Posts","description":"Retrieves the top performing posts for a specific hashtag. Returns up to 6 posts that used the hashtag, with comprehensive analytics metrics including engagement, reach, likes, comments, shares, and video views.","tags":["Analytics"],"parameters":[{"schema":{"type":"string"},"name":"Publer-Workspace-Id","in":"header","description":"ID of the workspace to retrieve posts from","required":true},{"schema":{"type":"string"},"name":"hashtag","in":"query","description":"The hashtag to retrieve performing posts for (with # symbol). This parameter is required to filter posts by the specific hashtag","required":true},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or after this date","required":false},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for posts data range (YYYY-MM-DD format). Filters posts scheduled on or before this date","required":false},{"schema":{"type":"string","enum":["scheduled_at","reach","engagement","engagement_rate","click_through_rate","reach_rate","postType","likes","video_views","comments","shares","saves","link_clicks","post_clicks"]},"name":"sort_by","in":"query","description":"Field to sort post results by. Supports various engagement and performance metrics","required":false},{"schema":{"type":"string","enum":["ASC","DESC"]},"name":"sort_type","in":"query","description":"Sort order direction","required":false},{"schema":{"type":"string"},"name":"account_id","in":"path","description":"Filter posts for a specific social media account ID. If omitted, includes all workspace accounts","required":false},{"schema":{"type":"string"},"name":"member_id","in":"query","description":"Filter posts by specific workspace member ID","required":false},{"schema":{"type":"string"},"name":"query","in":"query","description":"Search query to filter posts by content text, title, or link information using case-insensitive matching","required":false}],"responses":{"200":{"description":"Hashtag performing posts data with analytics metrics","content":{"application/json":{"schema":{"type":"array","description":"Array of top performing posts using the specified hashtag (up to 6 posts)","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the post"},"text":{"type":"string","description":"Post content text"},"title":{"type":"string","description":"Post title if available"},"scheduled_at":{"type":"string","format":"date-time","description":"Date and time when post was scheduled/published"},"account_id":{"type":"string","description":"ID of the social media account that published this post"},"hashtags":{"type":"array","description":"Array of hashtags used in this post","items":{"type":"string"}},"analytics":{"type":"object","description":"Comprehensive analytics data for the post","properties":{"reach":{"type":"integer","description":"Total reach of the post"},"likes":{"type":"integer","description":"Number of likes received"},"comments":{"type":"integer","description":"Number of comments received"},"shares":{"type":"integer","description":"Number of shares/reposts"},"engagement":{"type":"integer","description":"Total engagement (likes + comments + shares)"},"engagement_rate":{"type":"number","format":"float","description":"Engagement rate as percentage"},"video_views":{"type":"integer","description":"Number of video views (for video posts)"},"link_clicks":{"type":"integer","description":"Number of link clicks"},"post_clicks":{"type":"integer","description":"Number of post clicks"},"saves":{"type":"integer","description":"Number of saves/bookmarks"}}},"details":{"type":"object","description":"Additional post details and metadata","properties":{"labels":{"type":"array","description":"Labels assigned to this post","items":{"type":"object","properties":{"id":{"type":"string","description":"Label ID"},"name":{"type":"string","description":"Label name"}}}}}}}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/401ErrorResponse"}}}},"403":{"description":"Permission denied - requires analytics access or paying subscription","content":{"application/json":{"schema":{"$ref":"#/components/schemas/403ErrorResponse"}}}}}}}}}
```

### Notes

* Time range: Defaults to the workspace’s default range when not provided. “Last X Days” excludes partial data for the current day.
* Sorting & ranking: Use `sort_by` and `sort_type` to rank by Posts, Reach, Reactions (likes), Comments, Shares, or Video Views. UI columns can be reordered client‑side.
* Data freshness: Insights auto‑refresh every \~24h; you can manually sync in the UI for real‑time updates.
* Platform differences: Metrics availability varies by social network/account type; missing fields may be `null` or omitted.
* Pagination (insights list): `page` is 0‑based and returns 10 hashtags per page.
* Hashtag score: `hashtag_score (%) = (total hashtag engagement / total post engagement) × 100`.

### Related Resources

* [Post Insights](/docs/analytics/post-insights.md) — Per‑post performance analytics
* [Charts](/docs/analytics/charts.md) — Discover chart IDs and fetch chart data
* [Best Times](/docs/analytics/best-times-to-post.md) — Suggested posting time slots
* [Members](/docs/analytics/members.md) — Member (team) analytics


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://publer.com/docs/analytics/hashtag-analysis.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.