# Post Insights

The Post Insights endpoint retrieves detailed performance analytics for published posts, with powerful filtering, sorting, and pagination. Use it to build per-post dashboards, leaderboards, and competitor comparisons.

### Requirements

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

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

### Endpoint

#### Get Post Insights

Retrieve comprehensive analytics for posts within a workspace or a specific social account. Supports competitor analysis, text search, labels, post types, date ranges, member filtering, and multiple sort options.

```
GET /api/v1/analytics/:account_id/post_insights
```

#### Description

* When `:account_id` is a specific social account ID, results are limited to that account.
* When `:account_id` is omitted, results include all accessible accounts.
* Enable competitor mode with `competitors=true` and optionally narrow to a single competitor via `competitor_id` , see [Competitor Analysis](https://publer.com/docs/analytics/competitor-analysis) how to fetch competitor ids.

#### 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>Social account ID to scope results.<br>When used with competitors: true, it will filter all competitor posts related to this account.</td></tr></tbody></table>

#### Query Parameters

<table><thead><tr><th width="136.32025146484375">Parameter</th><th width="177.43426513671875">Type</th><th width="106.465576171875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>competitors</code></td><td>string</td><td>No</td><td>For competitor insights. <code>true</code> or <code>false</code> (default <code>false</code>).</td></tr><tr><td><code>competitor_id</code></td><td>string</td><td>No</td><td>Competitor account ID to analyze (requires <code>competitors=true</code>).</td></tr><tr><td><code>from</code></td><td>date (YYYY-MM-DD)</td><td>Yes</td><td>Start date (inclusive). Filters posts scheduled/published on or after this date.</td></tr><tr><td><code>to</code></td><td>date (YYYY-MM-DD)</td><td>Yes</td><td>End date (inclusive). Filters posts scheduled/published on or before this date.</td></tr><tr><td><code>query</code></td><td>string</td><td>No</td><td>Case-insensitive search across post text, title, link description, video title.</td></tr><tr><td><code>postType</code></td><td>string</td><td>No</td><td>Filter by post type. One of: <code>poll</code>, <code>status</code>, <code>link</code>, <code>carousel</code>, <code>photo</code>, <code>gif</code>, <code>video</code>, <code>reel</code>, <code>document</code>, <code>short</code>, <code>article</code>, <code>story</code>.</td></tr><tr><td><code>sort_by</code></td><td>string</td><td>No</td><td>Sort field. 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>Sort direction. <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 posts. Default <code>0</code>.</td></tr><tr><td><code>member_id</code></td><td>string</td><td>No</td><td>Filter by the workspace <a href="members">member</a> who created the post.</td></tr></tbody></table>

## Get Post Post Insights

> Retrieves comprehensive analytics data for published posts with advanced filtering, sorting, and pagination capabilities.

```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}/post_insights":{"get":{"summary":"Get Post Post Insights","description":"Retrieves comprehensive analytics data for published posts with advanced filtering, sorting, and pagination capabilities.","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","enum":["true","false"]},"name":"competitors","in":"query","description":"Include competitor analysis data. Set to 'true' to retrieve competitor post insights","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. Used with competitors parameter for competitor-specific analysis","required":false},{"schema":{"type":"string"},"name":"competitor_id","in":"query","description":"Specific competitor account ID to analyze when competitors=true. Works in conjunction with account_id parameter","required":false},{"schema":{"type":"string","format":"date"},"name":"from","in":"query","description":"Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date","required":true},{"schema":{"type":"string","format":"date"},"name":"to","in":"query","description":"End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date","required":true},{"schema":{"type":"string"},"name":"query","in":"query","description":"Search query to filter posts by text content, title, link description, or video title using case-insensitive matching","required":false},{"schema":{"type":"string","enum":["poll","status","link","carousel","photo","git","video","reel","document","short","article","story"]},"name":"postType","in":"query","description":"Filter posts by specific post type (e.g., image, video, link, text, carousel)","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 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":"integer","minimum":0},"name":"page","in":"query","description":"Page number for pagination (0-based indexing). Each page contains 10 posts","required":false},{"schema":{"type":"string"},"name":"member_id","in":"query","description":"Filter posts by specific workspace member/user ID who created or manages the posts","required":false}],"responses":{"200":{"description":"Post insights data with analytics metrics and pagination information","content":{"application/json":{"schema":{"type":"object","properties":{"posts":{"type":"array","description":"Array of posts with detailed analytics data","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"},"scheduled_at":{"type":"string","format":"date-time","description":"Date and time when post was scheduled/published"},"post_type":{"type":"string","description":"Type of post (image, video, link, etc.)"},"account_id":{"type":"string","description":"ID of the social media account"},"details":{"type":"object","properties":{"labels":{"type":"array","description":"Labels/tags associated with the post","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"color":{"type":"string"}}}}}},"analytics":{"type":"object","description":"Comprehensive analytics data for the post","properties":{"reach":{"type":"integer","description":"Number of unique users who saw the post"},"engagement":{"type":"integer","description":"Total engagement count (likes + comments + shares + saves + clicks)"},"engagement_rate":{"type":"number","format":"float","description":"Engagement rate as percentage"},"likes":{"type":"integer","description":"Number of likes/reactions"},"comments":{"type":"integer","description":"Number of comments"},"shares":{"type":"integer","description":"Number of shares/reposts"},"saves":{"type":"integer","description":"Number of saves/bookmarks"},"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 profile clicks"},"click_through_rate":{"type":"number","format":"float","description":"Click-through rate percentage"},"reach_rate":{"type":"number","format":"float","description":"Reach rate percentage"}}}}}},"total":{"type":"integer","description":"Total number of posts 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"}}}}}}}}}
```

### Notes

* Data sources: Metrics come from the official social network APIs. Insights auto‑sync periodically; you can manually sync in the UI for fresher data.
* Post vs aggregate reach: Post Insights show reach per post. Charts/overview may show total reach across all posts for a time window, so numbers won’t necessarily sum 1:1.
* Engagement formula: Typically the sum of likes/reactions + comments + shares + saves + post clicks (platform‑dependent).
  * Engagement Rate (%) ≈ `engagement / reach * 100`
  * Click‑Through Rate (%) ≈ `link_clicks / reach * 100`
  * Reach Rate (%) ≈ `reach / followers * 100` (where available)
* Platform differences: Not all metrics are available for all networks or account types (e.g., LinkedIn Profiles vs Pages).
* Pagination: Use `page` (0‑based). Each page returns 10 posts. Response includes `total` to compute more pages.
* Competitors: Requires `competitors=true`. Use `competitor_id` to focus on a single competitor’s posts; otherwise data may include multiple competitors (if enabled).

### Related Resources

* [Charts](https://publer.com/docs/analytics/charts) — Discover chart IDs and fetch chart data
* [Hashtag Analysis](https://publer.com/docs/analytics/hashtag-analysis) — Track hashtag performance
* [Best Times](https://publer.com/docs/analytics/best-times-to-post) — Suggested posting time slots
* [Members](https://publer.com/docs/analytics/members) — 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/post-insights.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.