> For the complete documentation index, see [llms.txt](https://help.blotato.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.blotato.com/api/analytics.md).

# Analytics

Blotato collects engagement analytics for your published posts across all 9 platforms (Twitter/X, Instagram, LinkedIn, Facebook, TikTok, Pinterest, Threads, Bluesky, YouTube). Two read-only endpoints expose this data:

* [List Top Performing Posts](#list-top-performing-posts) — `GET /v2/analytics`
* [Get Post Analytics](#get-post-analytics) — `GET /v2/posts/{id}/analytics`

Analytics is available on all plans, both in the [Blotato web app](https://my.blotato.com/published) (the **All** and **Top Performing** tabs on the Published page) and via the API documented below. Fair usage limits may apply in the future.

Both endpoints return the latest snapshot Blotato has already collected. They do not trigger a fresh fetch from the social platform.

***

## List Top Performing Posts

### Endpoint

**Base URL:** `https://backend.blotato.com/v2`

**URL:** `/analytics`

**Method:** `GET`

### Description

Returns your top performing published posts, ordered by the requested metric over a time range. Each item includes its latest metrics snapshot and full snapshot history.

### Query Parameters

| Field      | Type      | Required | Description                                                                                                                                                       |
| ---------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `since`    | `string`  | No       | Only include posts published on or after this ISO 8601 timestamp. Defaults to 30 days ago.                                                                        |
| `until`    | `string`  | No       | Only include posts published on or before this ISO 8601 timestamp. Defaults to now.                                                                               |
| `platform` | `string`  | No       | Filter to one platform: `twitter`, `instagram`, `linkedin`, `facebook`, `tiktok`, `pinterest`, `threads`, `bluesky`, or `youtube`. Omit to include all platforms. |
| `sortBy`   | `string`  | No       | Metric to rank by. One of `likes_count`, `comments_count`, `views_count`, `reach_count`. Default: `views_count`.                                                  |
| `limit`    | `integer` | No       | Number of posts to return. Min: 1, Max: 100. Default: 20.                                                                                                         |

### Response

**Status Code:** `200 OK`

```json
{
  "items": [
    {
      "id": "98431",
      "content": "Check out this image!",
      "postUrl": "https://instagram.com/p/abc123",
      "platform": "instagram",
      "createdAt": "2026-05-30T09:15:00.000Z",
      "mediaUrls": ["https://example.com/image1.jpg"],
      "latestMetrics": {
        "fetchedAt": "2026-06-11T12:00:00.000Z",
        "metrics": {
          "likesCount": "1240",
          "commentsCount": "85",
          "reachCount": "53000",
          "savesCount": "310"
        }
      },
      "metricsHistory": [
        {
          "fetchedAt": "2026-06-10T12:00:00.000Z",
          "metrics": { "likesCount": "1190", "reachCount": "51200" }
        },
        {
          "fetchedAt": "2026-06-11T12:00:00.000Z",
          "metrics": { "likesCount": "1240", "reachCount": "53000" }
        }
      ]
    }
  ]
}
```

#### Response Keys

| Field                    | Type             | Description                                                                                              |
| ------------------------ | ---------------- | -------------------------------------------------------------------------------------------------------- |
| `items`                  | `array`          | Published posts, ordered by the requested `sortBy` metric (highest first).                               |
| `items[].id`             | `string`         | The published post id. Pass this to [Get Post Analytics](#get-post-analytics).                           |
| `items[].content`        | `string`         | The post text.                                                                                           |
| `items[].postUrl`        | `string \| null` | Live URL of the published post. Null if the platform did not return one.                                 |
| `items[].platform`       | `string`         | Social media platform.                                                                                   |
| `items[].createdAt`      | `string`         | ISO 8601 timestamp when the post was published.                                                          |
| `items[].mediaUrls`      | `string[]`       | URLs of attached media. Empty when text-only.                                                            |
| `items[].latestMetrics`  | `object`         | The most recent metrics snapshot. Absent if no metrics have been collected yet. See [Metrics](#metrics). |
| `items[].metricsHistory` | `array`          | All collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`.                                 |

### Errors

| Status | Reason                                                |
| ------ | ----------------------------------------------------- |
| `422`  | Invalid `since`, `until`, `sortBy`, or `limit` value. |

### Example

```http
GET https://backend.blotato.com/v2/analytics?sortBy=views_count&platform=tiktok&limit=10 HTTP/1.1
blotato-api-key: YOUR_API_KEY
```

***

## Get Post Analytics

### Endpoint

**Base URL:** `https://backend.blotato.com/v2`

**URL:** `/posts/{id}/analytics`

**Method:** `GET`

### Description

Returns the latest metrics and full snapshot history for a single published post.

The `id` is the published post id, which you get from the `items[].id` field of [List Top Performing Posts](#list-top-performing-posts) or [List Posts](/api/publish-post/list-posts.md) (published items). It is not the `postSubmissionId` returned when you publish.

### Path Parameters

| Field | Type     | Required | Description                                  |
| ----- | -------- | -------- | -------------------------------------------- |
| `id`  | `string` | Yes      | The id of the published post (e.g. `12345`). |

### Response

**Status Code:** `200 OK`

```json
{
  "publishedPostId": "12345",
  "platform": "youtube",
  "lastFetchedAt": "2026-06-11T12:00:00.000Z",
  "lastError": null,
  "metrics": {
    "viewsCount": "18400",
    "likesCount": "920",
    "commentsCount": "47",
    "youtubeAverageViewPercentage": 62.5
  },
  "history": [
    {
      "fetchedAt": "2026-06-10T12:00:00.000Z",
      "metrics": { "viewsCount": "12100", "likesCount": "640" }
    },
    {
      "fetchedAt": "2026-06-11T12:00:00.000Z",
      "metrics": { "viewsCount": "18400", "likesCount": "920" }
    }
  ]
}
```

#### Response Keys

| Field             | Type             | Description                                                                                     |
| ----------------- | ---------------- | ----------------------------------------------------------------------------------------------- |
| `publishedPostId` | `string`         | The id of the published post.                                                                   |
| `platform`        | `string`         | Social media platform.                                                                          |
| `lastFetchedAt`   | `string \| null` | ISO 8601 timestamp of the most recent metrics fetch. Null if metrics have never been collected. |
| `lastError`       | `string \| null` | The last error Blotato hit while fetching metrics for this post, if any.                        |
| `metrics`         | `object \| null` | Latest metrics snapshot. Null if none collected yet. See [Metrics](#metrics).                   |
| `history`         | `array`          | All collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`.                        |

### Errors

| Status | Reason                                                                   |
| ------ | ------------------------------------------------------------------------ |
| `404`  | No published post with that `id`, or it does not belong to your account. |

### Example

```http
GET https://backend.blotato.com/v2/posts/12345/analytics HTTP/1.1
blotato-api-key: YOUR_API_KEY
```

***

## Metrics

Every metric field is optional and only appears when the platform reports it for that post. Count metrics are returned as strings to preserve large integers (e.g. `"18400"`). Rate and percentage metrics are returned as numbers.

### Common metrics (all platforms)

| Field                  | Description                               |
| ---------------------- | ----------------------------------------- |
| `viewsCount`           | Views.                                    |
| `impressionsCount`     | Impressions.                              |
| `reachCount`           | Unique accounts reached.                  |
| `likesCount`           | Likes.                                    |
| `commentsCount`        | Comments.                                 |
| `repliesCount`         | Replies.                                  |
| `sharesCount`          | Shares.                                   |
| `savesCount`           | Saves / bookmarks.                        |
| `clicksCount`          | Link or content clicks.                   |
| `followsCount`         | Follows gained from the post.             |
| `playsCount`           | Video/audio plays.                        |
| `profileVisitsCount`   | Profile visits driven by the post.        |
| `profileActivityCount` | Profile actions driven by the post.       |
| `navigationsCount`     | In-post navigation actions (e.g. swipes). |
| `interactionsSum`      | Total interactions.                       |
| `viewTimeMsSum`        | Total watch time, milliseconds.           |
| `watchTimeMsAvg`       | Average watch time, milliseconds.         |

### Platform-specific metrics

Each platform also returns its own metrics, prefixed with the platform name — for example `twitterRetweetsCount`, `linkedinFirstLevelCommentsCount`, `pinterestPinClicksCount`, `facebookTotalVideoViewsCount`, `youtubeAverageViewPercentage`. Breakdown metrics (such as `facebookPostReactionsByType` or `linkedinReactionsByType`) return an object mapping each bucket to a count, e.g. `{ "like": "13", "haha": "2" }`. Inspect the `metrics` object in the response for the full set available for your post.

***

## Related

* [List Posts](/api/publish-post/list-posts.md) — list scheduled, published, and failed posts; published items carry the `id` used by Get Post Analytics.
* `GET /v2/published-posts` — a paginated search over your published posts (filter by full-text `query` and `platform`) that attaches each post's latest analytics snapshot. Same item shape as [List Top Performing Posts](#list-top-performing-posts).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://help.blotato.com/api/analytics.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.