---
title: "Best-performing posts in the window by one metric"
method: GET
path: "/analytics/top-posts"
tags: ["Analytics"]
---

# Best-performing posts in the window by one metric

`GET /analytics/top-posts`

## Request

- Base URL: `https://post.adaptlypost.com/post/api/v1`
- URL: `https://post.adaptlypost.com/post/api/v1/analytics/top-posts`
- Auth: HTTP bearer

The top `limit` posts published inside the window, ordered by `sortBy` (default VIEWS). Same rows as /analytics/posts without pagination.. Requires the `analytics.read` permission.

## Query parameters

- `from` string, date-time, required
- `to` string, date-time, required
- `platforms` string[]
- `connectionIds` string[]
- `sortBy` 'VIEWS' | 'LIKES' | 'COMMENTS' | 'SHARES' | 'SAVES' | 'CLICKS' | 'IMPRESSIONS' | 'ENGAGEMENT_RATE' | 'PUBLISHED_AT'
- `limit` integer

## Headers

- `X-Workspace-Id` string

## Response `200`

Top posts

- object
  - `posts` AnalyticsPost[]
    - `id` string: Analytics record id. The only id every tracked post has, including posts discovered on the account
    - `postId` string, nullable: The AdaptlyPost post id (usable with /social-posts/{id}). Null for a post discovered on the account rather than published through AdaptlyPost
    - `postPlatformId` string, nullable: The `platformId` from /social-posts/{id}/results. Null for discovered posts
    - `platform` 'FACEBOOK' | 'INSTAGRAM' | 'THREADS' | 'TIKTOK' | 'TWITTER' | 'BLUESKY' | 'LINKEDIN' | 'PINTEREST' | 'YOUTUBE' | 'MASTODON' | 'TELEGRAM' | 'GOOGLE_BUSINESS' | 'TUMBLR'
    - `publishedAt` string, date-time
    - `title` string, nullable
    - `thumbnailUrl` string, nullable
    - `permalink` string, nullable: Public URL of the post on the platform, when known
    - `connectionId` string: The account `id` from /social-accounts that the post belongs to
    - `accountName` string, nullable
    - `metrics` AnalyticsPostMetrics: Latest captured counters for one post. A metric the platform does not report is null
      - `views` number, nullable
      - `likes` number, nullable
      - `comments` number, nullable
      - `shares` number, nullable
      - `saves` number, nullable
      - `clicks` number, nullable
      - `impressions` number, nullable
      - `reach` number, nullable
      - `engagementRate` number, nullable
      - `engagedViews` number, nullable: YouTube only. Views that played past the first frame, the way YouTube counted views before it began counting every start. Null on other platforms and until YouTube Analytics reports the video, which lags by a few days
      - `averageViewDurationSeconds` number, nullable: YouTube only. Average length of a playback, in seconds, over the video's lifetime. Null on other platforms and until YouTube Analytics reports the video
      - `averageViewPercentage` number, nullable: YouTube only. Average share of the video watched per playback, as a percentage (0-100, can exceed 100 when viewers rewatch). Null on other platforms and until YouTube Analytics reports the video

## Other responses

- `400`: Validation error
- `401`: Invalid or missing API key
- `403`: The key's role does not hold `analytics.read`
- `429`: Rate limit exceeded

---

[API](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api.md) · [All operations](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/adaptlypost/apis/adaptlypost-public-api/revisions/8390a5fa9a0d?raw)