# Post analytics

List every post with its metrics, sort and filter by engagement, look up one post across platforms, and chart day-by-day performance.

`GET /v1/analytics` returns your posts with their metrics. Without `postId` it is a paginated list with an overview block. With `postId` it returns one post and a breakdown per platform it went to.

## List posts with metrics

```bash cURL
curl "https://api.pozy.ai/v1/analytics?profileId=6650c1e2a3b4c5d6e7f80911&fromDate=2026-09-01&sortBy=engagement&limit=50" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/analytics?profileId=6650c1e2a3b4c5d6e7f80911&fromDate=2026-09-01&sortBy=engagement&limit=50", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const post of data.posts) {
  console.log(post.platform, post.analytics.likes, post.analytics.engagementRate);
}
```
```python Python
import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/analytics",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"profileId": "6650c1e2a3b4c5d6e7f80911", "fromDate": "2026-09-01", "sortBy": "engagement", "limit": 50},
    timeout=30,
)
for post in resp.json()["posts"]:
    print(post["platform"], post["analytics"]["likes"])
```

```json
{
  "overview": {
    "totalPosts": 142,
    "publishedPosts": 140,
    "scheduledPosts": 2,
    "lastSync": "2026-10-29T21:12:00Z",
    "dataStaleness": { "staleAccountCount": 0, "syncTriggered": false }
  },
  "posts": [
    {
      "_id": "6650c1e2a3b4c5d6e7f80e66",
      "platform": "instagram",
      "status": "published",
      "publishedAt": "2026-10-02T14:00:03Z",
      "platformPostUrl": "https://www.instagram.com/p/C7xYz12AbCd/",
      "analytics": { "impressions": 4210, "reach": 3105, "likes": 312, "comments": 41, "shares": 18, "saves": 27, "views": 3890, "engagementRate": 9.33, "lastUpdated": "2026-10-29T21:12:00Z" },
      "platforms": [{ "platform": "instagram", "syncStatus": "synced" }]
    }
  ],
  "pagination": { "page": 1, "limit": 50, "total": 142, "pages": 3 }
}
```

## Filters and sorting

| Parameter | What it does |
| --- | --- |
| `profileId`, `accountId`, `platform` | Narrow to a customer profile, one account or one platform |
| `source` | `all` (default), `pozy` for posts published through Pozy, `external` for posts made on the platform itself |
| `fromDate`, `toDate` | Bound the publish date. `fromDate` defaults to 90 days ago. The range is at most 366 days |
| `tags` | Only posts carrying these tags |
| `sortBy` | `date` (default), `engagement`, `impressions`, `reach`, `likes`, `comments`, `shares`, `saves`, `clicks`, `views`, `follows`, `reposts`, `profile_views`, `website_clicks`, `completion_rate`, `reels_skip_rate`, `ig_reels_avg_watch_time`, `ig_reels_video_view_total_time` |
| `order` | `desc` (default) or `asc` |
| `limit`, `page` | Up to 100 posts per page. Use `pagination.pages` to know when to stop |

A post sent to several platforms appears once per platform in the list, so key your own rows on post id plus platform.

## The metrics

Every post carries the same `analytics` object. A metric a platform does not report is `0` or `null`; check [Platform insights](https://pozy.ai/docs/analytics/platform-insights) for what each platform fills in.

| Field | Meaning |
| --- | --- |
| `impressions` | Times the post was shown |
| `reach` | Unique people who saw it |
| `likes`, `comments`, `shares`, `saves` | Engagement counters as the platform reports them |
| `clicks` | Link or profile clicks the post generated |
| `views` | Video or media views |
| `follows` | Followers gained from the post, where the platform says so |
| `reposts` | Reposts, where counted separately from shares |
| `profileViews`, `websiteClicks` | Profile visits and website taps the post brought in |
| `completionRate` | Share of viewers who watched to the end, from 0 to 1 |
| `igReelsAvgWatchTime`, `igReelsVideoViewTotalTime` | Average and total watch time in milliseconds (Instagram Reels and TikTok business accounts) |
| `reelsSkipRate` | Share of viewers who skipped a reel early |
| `impressionSources`, `audienceTypes`, `audienceCountries` | Breakdowns as shares from 0 to 1, where the platform provides them |
| `retentionCurve` | Share of viewers still watching at each second |
| `engagementRate` | Likes, comments, shares and saves over impressions, as a percentage |
| `lastUpdated` | When Pozy last refreshed these numbers |

## One post across platforms

Pass `postId` (a Pozy post id or an external post id) to get a single post with a `platformAnalytics` array, one entry per platform it was published to:

```bash cURL
curl "https://api.pozy.ai/v1/analytics?postId=6650c1e2a3b4c5d6e7f80e66" \
  -H "Authorization: Bearer $POZY_API_KEY"
```
```ts Node
const res = await fetch("https://api.pozy.ai/v1/analytics?postId=6650c1e2a3b4c5d6e7f80e66", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data.error);

for (const p of data.platformAnalytics) {
  console.log(p.platform, p.syncStatus, p.analytics?.views);
}
```
```python Python
resp = requests.get(
    "https://api.pozy.ai/v1/analytics",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={"postId": "6650c1e2a3b4c5d6e7f80e66"},
    timeout=30,
)
print(resp.json()["platformAnalytics"])
```

Each `platformAnalytics` entry has its own `syncStatus` (`synced`, `pending`, `unavailable`), `platformPostUrl` and, when something went wrong, `errorCode`: `post_not_found` (deleted on the platform), `not_post_owner` or `permission_missing`.

> **Note:**
> 
> A single-post lookup answers `202` while its first sync is still running. Retry after a short wait. It answers `424` when every platform failed to sync.

## Day by day

Two endpoints give you a time series instead of lifetime totals.

**One post over time.** [`GET /v1/analytics/post-timeline`](https://pozy.ai/docs/api/getPostTimeline) with `postId` returns one row per day per platform, showing how impressions, likes and the other counters grew since publishing.

**All posts, summed per day.** [`GET /v1/analytics/daily-metrics`](https://pozy.ai/docs/api/getDailyMetrics) returns a `dailyData` array (post count, platform split and summed metrics per day) plus a `platformBreakdown`. It defaults to the last 180 days. Its `attribution` parameter decides what a day means:

| `attribution` | A day shows | Answers |
| --- | --- | --- |
| `publish` (default) | Lifetime totals of the posts published that day | "How did what I published this week do?" |
| `received` | Engagement that arrived that day, on any post | "How much engagement did the account get this week?" |

A post published on 1 July gets 40 likes that day and 10 more on 20 July. Under `publish`, all 50 sit on 1 July. Under `received`, 1 July shows 40 and 20 July shows 10. Use `received` for account overview charts, because it moves even in weeks with no new posts.

## Followers

Follower counts live on the accounts side: [`GET /v1/accounts/follower-stats`](https://pozy.ai/docs/api/getFollowerStats) takes `profileId` or `accountIds`, a date range and `granularity` (`daily`, `weekly` or `monthly`). Counts refresh once a day, so a daily job is enough.

## Exports

There is no separate export endpoint. To export, page through `GET /v1/analytics` (100 posts per page) or the delta feed and write the rows to CSV yourself. Each row already has the post URL, platform, publish time and every metric.

## Endpoints

| Endpoint | What it does |
| --- | --- |
| [`GET /v1/analytics`](https://pozy.ai/docs/api/getAnalytics) | Get post analytics |
| [`GET /v1/analytics/post-timeline`](https://pozy.ai/docs/api/getPostTimeline) | Get post analytics timeline |
| [`GET /v1/analytics/daily-metrics`](https://pozy.ai/docs/api/getDailyMetrics) | Get daily aggregated metrics |
| [`GET /v1/analytics/delta`](https://pozy.ai/docs/api/getAnalyticsDelta) | Analytics changed since a cursor |
| [`GET /v1/accounts/follower-stats`](https://pozy.ai/docs/api/getFollowerStats) | Get follower stats |
| [`POST /v1/posts/sync-external`](https://pozy.ai/docs/api/syncExternalPosts) | Sync an external post |