> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overlap.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Analytics Model

> Field reference for the Post and Analytics objects returned by the analytics endpoints

Reference for the objects returned by [`GET /posts`](/api-reference/posts) and [`GET /post-analytics`](/api-reference/post-analytics). Fields are included when available — a response may omit values that have not been generated yet (for example, `engagementScore` before the first analytics refresh).

## Post object

| Field                 | Type              | Description                                                                                                                                                                           |
| --------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | string            | The post id. Use as `postId` for `GET /post-analytics`.                                                                                                                               |
| `platform`            | string            | Platform the post was published to (`youtube`, `tiktok`, `instagram`, `twitter`, `linkedin`, `facebook`, `threads`, `snapchat`, `bluesky`).                                           |
| `text`                | string            | The caption/description that was published.                                                                                                                                           |
| `postUrl`             | string \| null    | Public URL of the live post on the platform.                                                                                                                                          |
| `nativeId`            | string \| null    | The platform's own id for the post (e.g. the YouTube video id).                                                                                                                       |
| `clipId`              | string \| null    | The Overlap clip the post was created from. Use with `GET /clip`.                                                                                                                     |
| `status`              | string            | Publish status (`success`, `error`, ...).                                                                                                                                             |
| `mediaUrl`            | string \| null    | The rendered video/image that was published.                                                                                                                                          |
| `thumbnailUrl`        | string \| null    | Thumbnail used for the post.                                                                                                                                                          |
| `createdAt`           | string (ISO-8601) | When the post was published.                                                                                                                                                          |
| `analytics`           | object            | Current rolled-up counters — see below. In `GET /posts` responses this object sits on each post; in `GET /post-analytics` it is returned as the top-level `analytics` object instead. |
| `engagementScore`     | number            | See [Engagement score](#engagement-score).                                                                                                                                            |
| `growthRate`          | number            | Percentage growth of the engagement score between the two most recent refreshes.                                                                                                      |
| `lastAnalyticsUpdate` | string (ISO-8601) | When the rollup was last refreshed from the platform.                                                                                                                                 |

## Analytics rollup object

| Field                 | Type              | Description                                                                                                                                                                                                                                                                                                                                                |
| --------------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `views`               | number            | Current view count. Impressions are used on platforms without a native view metric. Always `0` on Bluesky (no per-post views).                                                                                                                                                                                                                             |
| `likes`               | number            | Current likes/favorites.                                                                                                                                                                                                                                                                                                                                   |
| `comments`            | number            | Current comments/replies.                                                                                                                                                                                                                                                                                                                                  |
| `shares`              | number            | Current shares/reposts/retweets.                                                                                                                                                                                                                                                                                                                           |
| `engagementScore`     | number            | See [Engagement score](#engagement-score).                                                                                                                                                                                                                                                                                                                 |
| `growthRate`          | number            | Engagement score growth (%) between the last two refreshes.                                                                                                                                                                                                                                                                                                |
| `lastAnalyticsUpdate` | string (ISO-8601) | Last refresh time.                                                                                                                                                                                                                                                                                                                                         |
| `platformMetrics`     | object            | The platform's own advanced metrics from the most recent refresh, keyed by platform (e.g. `{"youtube": {"analytics": {"averageViewDuration": 21, ...}}}`). Includes whatever the platform reports — watch time, retention, impressions, subscriber deltas. Shapes mirror the platforms' APIs and may change without notice. Only on `GET /post-analytics`. |

## Engagement score

A single number Overlap computes to compare posts across platforms:

```
engagementScore = (likes × 2) + (comments × 3) + (shares × 4) + max(5, views / 100)
```

Weighted toward high-intent actions (shares > comments > likes), with a views term so view-heavy posts still register. Use it for relative ranking; it has no absolute unit.

<CardGroup cols={2}>
  <Card title="List Posts" icon="list" href="/api-reference/posts">
    Browse posts and rolled-up metrics.
  </Card>

  <Card title="Post Analytics" icon="chart-line" href="/api-reference/post-analytics">
    All current analytics for one post.
  </Card>
</CardGroup>
