Skip to main content
GET
/
api
/
partner
/
v1
/
analytics
/
summary
/
posts
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>'

{
  "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
  }
}
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

​
range
string
default:"30d"
Date preset: 14d, 30d, 90d, 1y, all.
​
start
string
Custom range start date (YYYY-MM-DD). Must be paired with end.
​
end
string
Custom range end date (YYYY-MM-DD). Must be paired with start.
​
platforms
string
Comma-separated platform filter (for example: tiktok,instagram). You can also use platform.
​
accounts
string
Comma-separated analytics target IDs. You can also use account_ids.
​
sortBy
string
default:"published_at"
Sort field: published_at, views, likes, comments, shares. You can also use sort_by.
​
sortOrder
string
default:"desc"
Sort direction: asc or desc. You can also use sort_order.
​
limit
number
default:"50"
Page size, max 100.
​
offset
number
default:"0"
Offset for pagination. Maximum 10000.

​
Response

​
posts
array
Array of analytics post rows with metrics and account context.
​
totalCount
number
Total matching rows for the selected filters.
​
hasMore
boolean
Whether additional rows are available.
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>'

{
  "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
  }
}

​
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.