---
title: "List top-performing posts"
method: GET
path: "/v0/analytics/top-posts"
tags: ["Analytics"]
---

# List top-performing posts

`GET /v0/analytics/top-posts`

## Request

- Base URL: `https://api.schedulin.app`
- URL: `https://api.schedulin.app/v0/analytics/top-posts`
- Auth: one of:
  - API key in header `x-api-key`
  - OAuth 2 (authorization code, authorization URL `https://api.schedulin.app/oauth/authorize`, token URL `https://api.schedulin.app/oauth/token`, scopes: `analytics:read`)

Posts ranked by `metric` (default `engagementTotal`) accumulated within the window. Covers posts published from the workspace's connected accounts. Filter with `platforms` and `socialAccountIds`; `from`/`to` may span up to 400 days. Metrics are collected periodically per post, so the most recent hours may still be filling in.

## Query parameters

- `from` string, required: Start of the window (inclusive), ISO 8601. The window may span up to 400 days.
- `to` string, required: End of the window (exclusive), ISO 8601
- `platforms` string[]: Only include these platforms
- `socialAccountIds` string[]: Only include these social accounts
- `metric` 'impressions' | 'reach' | 'likes' | 'comments' | 'shares' | 'saves' | 'videoViews' | 'engagementTotal': Metric to rank by
- `limit` integer

## Response `200`

OK

- object
  - `posts` object[], required
    - `id` string, required
    - `platform` string, required
    - `caption` string, nullable, required
    - `url` string, nullable, required
    - `createdAt` string, date-time, nullable, required
    - `value` integer, required: The ranking metric's total within the window

## Other responses

- `400`: Bad Request — the request isn't allowed in the resource's current state (e.g. editing a published post).
- `401`: Unauthorized — missing or invalid API key / access token.
- `403`: Forbidden — the credential lacks the required scope or access.
- `422`: Unprocessable request. Schema validation failures have `code: "INPUT_VALIDATION_FAILED"` and `data.fieldErrors` mapping each invalid field to its messages (nested issues name their full path, e.g. `media[0].url: ...`). Business-rule rejections (e.g. a `scheduledAt` in the past) have `code: "UNPROCESSABLE_CONTENT"` and carry the reason in `data.message` and `data.formErrors`.
- `429`: Rate limit exceeded. Wait `Retry-After` seconds before retrying.
- `500`: Internal Server Error

---

[API](https://skmtc.dev/schedulin/apis/schedulin-api.md) · [All operations](https://skmtc.dev/schedulin/apis/schedulin-api/llms.txt) · [OpenAPI document](https://skmtc.dev/schedulin/apis/schedulin-api/revisions/17e886f3bcf3?raw)