> For the complete documentation index, see [llms.txt](https://help.contouron.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.contouron.com/api/analytics.md). # Analytics > For the complete documentation index, see [llms.txt](https://help.contouron.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.contouron.com/api/analytics.md). ## Analytics Contouron collects engagement analytics for your published posts on 5 platforms: Twitter/X, Instagram, Facebook, Threads, and Bluesky. Analytics for TikTok, YouTube, Pinterest, and LinkedIn are not available yet. 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 paid plans, both in the [Contouron web app](https://my.contouron.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 Contouron has already collected. They do not trigger a fresh fetch from the social platform. #### Collection schedule Contouron collects a snapshot of each post's metrics at fixed checkpoints, measured from when the post publishes. The number of checkpoints depends on your plan. | Checkpoint after publish | Starter | Creator | Agency | | ------------------------ | :-----: | :-----: | :----: | | 2 hours | | ✓ | ✓ | | 6 hours | | | ✓ | | 1 day | ✓ | ✓ | ✓ | | 7 days | ✓ | ✓ | ✓ | | 14 days | | | ✓ | | 30 days | | ✓ | ✓ | | 90 days | | | ✓ | Each checkpoint adds a small random delay to spread out collection, so exact timing varies by a few minutes to a few hours. Posts that spike early can receive extra checkpoints beyond your plan's schedule. #### Posts stuck on "Analytics pending" If posts on a supported platform stay on "Analytics pending" for days on a paid plan, the connected account most likely predates the analytics feature. Analytics needs updated account permissions, so reconnect the social account in [Settings](https://my.contouron.com/settings) to grant them. This applies to accounts (Instagram, Facebook, and others) connected before analytics launched. New metrics collect from the next checkpoint after you reconnect. If you already reconnected, no further action is needed. The first batch of metrics appears within 24-48 hours of reconnecting, then collection follows your plan's checkpoint schedule above. *** ### List Top Performing Posts #### Endpoint **Base URL:** `https://backend.contouron.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`, or `bluesky`. Omit to include all platforms. Analytics for `tiktok`, `youtube`, `pinterest`, and `linkedin` are not available yet, so filtering to those returns no metrics. | | `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.contouron.com/v2/analytics?sortBy=views_count&platform=instagram&limit=10 HTTP/1.1 contouron-api-key: YOUR_API_KEY ``` *** ### Get Post Analytics #### Endpoint **Base URL:** `https://backend.contouron.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 (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": "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 most recent metrics fetch. Null if metrics have never been collected. | | `lastError` | `string \| null` | The last error Contouron 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.contouron.com/v2/posts/12345/analytics HTTP/1.1 contouron-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" }`. 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 `facebookTotalVideoViewsCount`. See the Metrics Reference 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. Inspect the `metrics` object in the response for the full set available for your post. *** ### Related * List Posts — list scheduled, published, and failed posts; published items carry the `id` used by Get Post Analytics. * List Published Posts — 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 dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.contouron.com/api/analytics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.