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.

```plaintext
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) for how to fetch competitor ids.

#### URL Parameter

| Parameter     | Type   | Required | Description                                                                                       |
|---------------|--------|----------|---------------------------------------------------------------------------------------------------|
| `account_id`  | string | No       | Social account ID to scope results. When used with competitors: true, it will filter all competitor posts related to this account.

#### Query Parameters

| Parameter         | Type               | Required | Description                                                                                     |
|-------------------|--------------------|----------|-------------------------------------------------------------------------------------------------|
| `competitors`     | string             | No       | For competitor insights. `true` or `false` (default `false`).                                   |
| `competitor_id`   | string             | No       | Competitor account ID to analyze (requires `competitors=true`).                                 |
| `from`            | date (YYYY-MM-DD)  | Yes      | Start date (inclusive). Filters posts scheduled/published on or after this date.                |
| `to`              | date (YYYY-MM-DD)  | Yes      | End date (inclusive). Filters posts scheduled/published on or before this date.                |
| `query`           | string             | No       | Case-insensitive search across post text, title, link description, video title.                  |
| `postType`        | string             | No       | Filter by post type. One of: `poll`, `status`, `link`, `carousel`, `photo`, `gif`, `video`, `reel`, `document`, `short`, `article`, `story`.
| `sort_by`         | string             | No       | Sort field. One of: `scheduled_at`, `reach`, `engagement`, `engagement_rate`, `click_through_rate`, `reach_rate`, `postType`, `likes`, `video_views`, `comments`, `shares`, `saves`, `link_clicks`, `post_clicks`. Default `scheduled_at`.
| `sort_type`       | string             | No       | Sort direction. `ASC` or `DESC`. Default `DESC`.                                              |
| `page`            | integer            | No       | Page number (0-based). Each page contains 10 posts. Default `0`.                                |
| `member_id`      | string             | No       | Filter by the workspace member who created the post.                                           |

### Get Post Post Insights

```plaintext
GET https://app.publer.com/api/v1/analytics/{account_id}/post_insights
```

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

#### Authorizations

- Bearer

| Path parameters      | Type       | Required | Description                                                                                                         |
|----------------------|------------|----------|---------------------------------------------------------------------------------------------------------------------|
| `account_id`        | string     | Optional | Filter posts for a specific social media account ID. If omitted, includes all workspace accounts. Used with competitors parameter for competitor-specific analysis.

#### Query parameters

- **competitors:** string · enum (Optional) - Include competitor analysis data. Set to 'true' to retrieve competitor post insights
- **from:** string · date (Required) - Start date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or after this date
- **to:** string · date (Required) - End date for post insights data range (YYYY-MM-DD format). Filters posts scheduled on or before this date
- **query:** string (Optional) - Search query to filter posts by text content, title, link description, or video title using case-insensitive matching
- **postType:** string · enum (Optional) - Filter posts by specific post type (e.g., image, video, link, text, carousel)
- **sort_by:** string · enum (Optional) - Field to sort results by. Supports various engagement and performance metrics
- **sort_type:** string · enum (Optional) - Sort order direction
- **page:** integer (Optional) - Page number for pagination (0-based indexing). Each page contains 10 posts
- **member_id:** string (Optional) - Filter posts by specific workspace member/user ID who created or manages the posts.

### Responses

- **200** - Post insights data with analytics metrics and pagination information
- **401** - Unauthorized
- **403** - Permission denied - requires analytics access or paying subscription

```json
{
  "posts": [
    {
      "id": "text",
      "text": "text",
      "title": "text",
      "scheduled_at": "2026-04-29T16:24:18.859Z",
      "post_type": "text",
      "account_id": "text",
      "details": {
        "labels": [
          {
            "id": "text",
            "name": "text",
            "color": "text"
          }
        ]
      },
      "analytics": {
        "reach": 1,
        "engagement": 1,
        "engagement_rate": 1,
        "likes": 1,
        "comments": 1,
        "shares": 1,
        "saves": 1,
        "video_views": 1,
        "link_clicks": 1,
        "post_clicks": 1,
        "click_through_rate": 1,
        "reach_rate": 1
      }
    }
  ],
  "total": 1
}
```

### 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).