> 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/rest-api-reference/analytics.md). # Analytics Blotato collects engagement analytics for your published posts on 8 platforms: Twitter/X, Instagram, Facebook, Threads, Bluesky, TikTok, YouTube, and Pinterest. Analytics for LinkedIn are not available yet. Four read-only endpoints expose this data: * [List Top Performing Posts](#list-top-performing-posts) — `GET /v2/analytics` * [List Performance by Platform](#list-performance-by-platform) — `GET /v2/analytics/platforms` * [Get Analytics Summary](#get-analytics-summary) — `GET /v2/analytics/summary` * [Get Post Analytics](#get-post-analytics) — `GET /v2/posts/{id}/analytics` Analytics is available on all paid plans, both in the [Analytics dashboard](https://my.blotato.com/analytics) and via the API documented below. Fair usage limits may apply in the future. For a web-app and AI-agent walkthrough, see [Analytics](/web-app-features/analytics.md). Both endpoints return the latest snapshot Blotato has already collected. They do not trigger a fresh fetch from the social platform. ### Using analytics from Make.com or n8n The official Blotato Make.com module does not include analytics yet. To pull analytics from a Make scenario, call the two endpoints on this page with Make's HTTP module, passing your API key in the `blotato-api-key` header. The same approach works in n8n with the HTTP Request node. ### Collection schedule Blotato collects a snapshot of each post's metrics at fixed checkpoints, measured from when the post publishes. Higher plans collect more often and keep collecting longer. | Plan | Checkpoints per post | Collection window | Cadence | | ------- | :------------------: | ----------------- | ------------------------------------------------------------------------------ | | Starter | 4 | 30 days | Day 1, then days 7, 14, and 30 | | Creator | 18 | 30 days | 2 hours, daily through day 8, then every 2-3 days through day 30 | | Agency | 20 | 90 days | 2 and 6 hours, daily through day 8, every 2-3 days through day 30, then day 90 | Full checkpoint list per plan: * **Starter:** 1d, 7d, 14d, 30d * **Creator:** 2h, 1d, 2d, 3d, 4d, 5d, 6d, 7d, 8d, 10d, 12d, 14d, 17d, 20d, 22d, 24d, 27d, 30d * **Agency:** 2h, 6h, 1d, 2d, 3d, 4d, 5d, 6d, 7d, 8d, 10d, 12d, 14d, 17d, 20d, 22d, 24d, 27d, 30d, 90d Each checkpoint adds a small random offset to spread out collection, so exact timing varies by a few minutes on the early checkpoints and up to a day on the 30-day and 90-day ones. After the final checkpoint, Blotato stops collecting and the last snapshot stays as the post's metrics. ### Posts stuck on "Analytics pending" "Analytics pending" means no metric history is available. It does not identify the cause. 1. Check the platform and plan against the supported metrics. 2. Check whether the post was published through Blotato with analytics enabled. 3. Compare the post's age with its plan's checkpoints. 4. Inspect `lastError` and the account's connection state. Reconnect when authorization is missing or expired, not as a repeated generic fix. 5. If the expected checkpoint has passed and no cause is established, give support the published post ID, publication time, platform, plan, last fetch time, and error. Reconnection does not guarantee a 24-48-hour backfill or a restart of every historical post's schedule. See [new connections and pending data](/web-app-features/analytics.md#i-just-connected-an-account-when-will-analytics-appear). ### YouTube view counts trail the public count For YouTube, Blotato reads the YouTube Analytics API, which reports only finalized views after YouTube filters spam and invalid traffic. The count on the YouTube watch page updates in near real time and includes views YouTube has not validated yet, so it reads higher. The two numbers are not expected to match, and the gap narrows as YouTube finalizes more data. See: [Why is my YouTube view count in Blotato lower than on YouTube?](/support/faqs.md#why-is-my-youtube-view-count-in-blotato-lower-than-on-youtube) *** ## 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`, `facebook`, `threads`, `bluesky`, `tiktok`, `youtube`, or `pinterest`. Omit to include all platforms. Analytics for `linkedin` are not available yet, so filtering to it returns no metrics. | | `sortBy` | `string` | No | Metric to rank by. One of `likes_count`, `comments_count`, `views_count`, `reach_count`. Default: `views_count`. For Twitter/X, `comments_count` uses `replies_count` when comments are not reported, and `views_count` uses `impressions_count` when views are not reported. | | `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). Twitter/X rankings use `replies_count` as the comments fallback and `impressions_count` as the views fallback. | | `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=instagram&limit=10 HTTP/1.1 blotato-api-key: YOUR_API_KEY ``` *** ## List Performance by Platform **URL:** `/analytics/platforms` **Method:** `GET` Returns 1 entry per platform with analytics, ordered by engagement. Totals use the latest snapshot of each post published in the window. | Field | Type | Required | Description | | -------- | -------- | -------- | -------------------------------------------------------------------------------------- | | `since` | `string` | No | Include posts published on or after this ISO 8601 timestamp. Defaults to 24 hours ago. | | `until` | `string` | No | Include posts published on or before this ISO 8601 timestamp. Defaults to now. | | `bucket` | `string` | No | Time bucket size: `hour` or `day`. Defaults to `hour`. | Each item contains `platform`, `postsCount`, `engagementsCount`, `likesCount`, `commentsCount`, `viewsCount`, and `buckets`. Counts are strings except `postsCount`. `viewsCount` is null when the platform reports neither views nor impressions. Engagements are the sum of likes, comments or replies, shares, and saves. *** ## Get Analytics Summary **URL:** `/analytics/summary` **Method:** `GET` Returns published and failed post counts for a time window, both in total and grouped by platform and time bucket. It also returns metric totals from each published post's latest snapshot. | Field | Type | Required | Description | | -------- | -------- | -------- | ----------------------------------------------------------------------------------------------- | | `since` | `string` | No | Include posts published or failed on or after this ISO 8601 timestamp. Defaults to 30 days ago. | | `until` | `string` | No | Include posts published or failed on or before this ISO 8601 timestamp. Defaults to now. | | `bucket` | `string` | No | Time bucket size: `hour` or `day`. Defaults to `hour`. | The response contains `publishedCount`, `failedCount`, `platforms`, `buckets`, and `metrics`. `metrics` contains `postsCount`, `viewsCount`, `likesCount`, and `commentsCount`, or is null when analytics is unavailable. *** ## 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](/rest-api-reference/publish-post/list-posts.md) (published items). It is not the `postSubmissionId` returned when you publish. If your request returns only `postSubmissionId`, `status`, and `publicUrl` with no metrics fields, you called [Get Post Status](/rest-api-reference/publish-post/get-post.md) instead of this analytics endpoint. Get Post checks publish status with the `postSubmissionId`. Analytics uses the published post id from List Posts or List Top Performing Posts. ### Path Parameters | Field | Type | Required | Description | | ----- | -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | `string` | Yes | The published post ID from `items[].id` in [List Top Performing Posts](#list-top-performing-posts) or a published item in [List Posts](/rest-api-reference/publish-post/list-posts.md). Do not substitute a `postSubmissionId`. The analytics path ends in `/analytics`, whereas the publishing-status path does not. | ### Response **Status Code:** `200 OK` ```json { "publishedPostId": "12345", "platform": "instagram", "lastFetchedAt": "2026-06-11T12:00:00.000Z", "lastError": null, "metrics": { "viewsCount": "18400", "likesCount": "920", "commentsCount": "47", "reachCount": "56200" }, "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 last snapshot stored successfully. A failed fetch leaves this unchanged, so it reflects the last success, not the last attempt. Check `lastError` for the most recent failure. | | `lastError` | `string \| null` | The last error Blotato hit while fetching metrics for this post, if any. | | `metrics` | `object \| null` | Latest metrics snapshot. See [Metrics](#metrics) and [Empty vs null metrics](#empty-vs-null-metrics). | | `history` | `array` | All collected snapshots, oldest first. Each is `{ fetchedAt, metrics }`. | ### Errors | Status | Reason | | ------ | -------------------------------------------------------------------------------------------------------------- | | `404` | No published post with that `id`, it does not belong to your account, or your plan does not include analytics. | ### 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, and breakdown metrics (such as `facebookPostReactionsByType`) return an object mapping each bucket to a count, e.g. `{ "like": "13", "haha": "2" }`. A metric value of `0` is real and is always returned. It means zero, not missing. ### Empty vs null metrics An empty `metrics` object (`{}`) is not the same as `metrics: null`. * `metrics: null` -- no analytics snapshot has been stored yet. * `metrics: {}` -- a snapshot exists, but no metric values are being returned. Two causes: every value came back empty from the platform, or your plan returns a reduced metric set. Common metrics like `viewsCount`, `likesCount`, and `reachCount` apply across platforms. Each platform also returns its own metrics, prefixed with the platform name — for example `twitterRetweetsCount` or `blueskyRepostsCount`. See the [Metrics Reference](/rest-api-reference/analytics/analytics-metrics.md) for the full list of common and platform-specific metrics. Platform-specific coverage depends on your plan. The Starter plan returns a limited set of these metrics. The Creator and Agency plans return every platform-specific metric and breakdown. See the [Metrics Reference](/rest-api-reference/analytics/analytics-metrics.md) for the field-level breakdown. Inspect the `metrics` object in the response for the set available for your post. *** ## Related * [List Posts](/rest-api-reference/publish-post/list-posts.md) — list scheduled, published, and failed posts; published items carry the `id` used by Get Post Analytics. * [List Published Posts](/rest-api-reference/publish-post/list-published-posts.md) — full-text search over your published posts with the latest analytics snapshot attached. --- # 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 by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://help.blotato.com/rest-api-reference/analytics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.