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

# List Analytics Posts

> Fetch paginated post-level analytics across tracked accounts

Returns post analytics from the same summary-posts dataset used in the internal
analytics UI, including platform/account context, sortable metrics, and
partner-post correlation fields when the analytics post can be matched back to
an originating Genviral post.

## Query Parameters

<ParamField query="range" type="string" default="30d">
  Date preset: `14d`, `30d`, `90d`, `1y`, `all`.
</ParamField>

<ParamField query="start" type="string">
  Custom range start date (`YYYY-MM-DD`). Must be paired with `end`.
</ParamField>

<ParamField query="end" type="string">
  Custom range end date (`YYYY-MM-DD`). Must be paired with `start`.
</ParamField>

<ParamField query="platforms" type="string">
  Comma-separated platform filter (for example: `tiktok,instagram`). You can
  also use `platform`.
</ParamField>

<ParamField query="accounts" type="string">
  Comma-separated analytics target IDs. You can also use `account_ids`.
</ParamField>

<ParamField query="sortBy" type="string" default="published_at">
  Sort field: `published_at`, `views`, `likes`, `comments`, `shares`. You can
  also use `sort_by`.
</ParamField>

<ParamField query="sortOrder" type="string" default="desc">
  Sort direction: `asc` or `desc`. You can also use `sort_order`.
</ParamField>

<ParamField query="limit" type="number" default="50">
  Page size, max `100`.
</ParamField>

<ParamField query="offset" type="number" default="0">
  Offset for pagination. Maximum `10000`.
</ParamField>

## Response

<ResponseField name="posts" type="array">
  Array of analytics post rows with metrics and account context.
</ResponseField>

<ResponseField name="totalCount" type="number">
  Total matching rows for the selected filters.
</ResponseField>

<ResponseField name="hasMore" type="boolean">
  Whether additional rows are available.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://www.genviral.io/api/partner/v1/analytics/summary/posts?range=90d&sortBy=views&sortOrder=desc&limit=25&offset=0' \
    --header 'Authorization: Bearer <token>'
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "ok": true,
    "code": 200,
    "message": "Analytics posts retrieved",
    "data": {
      "posts": [
        {
          "id": "88c2011d-c620-4b61-8486-78e8f182e8ec",
          "analyticsId": "88c2011d-c620-4b61-8486-78e8f182e8ec",
          "platformPostId": "7391929919011",
          "genviralPostId": "d0e1d35c-d34c-4503-afe8-3c56e4aa1911",
          "externalId": "automation-1e93c16b-4866-43ed-82e9-ea55bae5e1ab",
          "publishedAt": "2026-02-12T17:42:02.000Z",
          "caption": "How to prep your first week of content",
          "permalink": "https://www.tiktok.com/@brand/video/7391929919011",
          "thumbnailUrl": "https://cdn.example.com/thumb.jpg",
          "durationSeconds": 27,
          "metrics": {
            "views": 14120,
            "likes": 812,
            "comments": 67,
            "shares": 29,
            "saves": 14
          },
          "engagementRate": 6.42,
          "platform": "tiktok",
          "accountIdentifier": "@brand",
          "accountDisplayName": "Brand HQ",
          "accountAvatarUrl": null
        }
      ],
      "totalCount": 192,
      "hasMore": true
    }
  }
  ```
</ResponseExample>

## Notes

* `id` is the analytics-row ID for this analytics dataset.
* `analyticsId` is the explicit analytics-row ID. `id` is retained as a legacy
  alias for backward compatibility.
* `platformPostId` is the platform-native post/video ID when available.
* `genviralPostId` is the originating Genviral post ID when the analytics row
  can be correlated back to a created/scheduled post.
* `externalId` is the originating Partner API `external_id` when available.
* `genviralPostId` and `externalId` are `null` when a row cannot be correlated
  back to a Partner/Genviral-created post.
* For BYO TikTok `MEDIA_UPLOAD`, correlation is best-effort for recent
  unresolved drafts after the human publishes in TikTok. Older rows can remain
  uncorrelated until a future async reconciliation/backfill exists.

## Error Responses

* `400` - invalid query parameters (`range`, `platforms`, `sortBy`, `sortOrder`, `limit`, `offset`, `start/end`)
* `401`/`403` - authentication failed or key lacks workspace access
* `500` - unexpected analytics query error

All error responses from analytics endpoints include an `error_code` field.