# TikTok post insights

> Counters and watch metrics for TikTok posts.

Canonical: <https://www.tryadeli.com/docs/api/analytics/tiktok-post-insights>

`GET https://app.tryadeli.com/api/v1/analytics/tiktok/video-insights`

Authorization: `Bearer <API key>` — see [Authentication](https://www.tryadeli.com/docs/authentication)

Returns counters and watch metrics for specific TikTok posts, or for the most
recent page of posts when `videoIds` is omitted. Needs the `video.insights`
permission.

**Query parameters**

| Name        | Type     | Required | Description                                                                                                        |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
| `accountId` | `uuid`   | Yes      | A connected TikTok account.                                                                                        |
| `profileId` | `uuid`   |          | Optional, because accountId names its profile. If you pass both, they must agree.                                  |
| `videoIds`  | `string` |          | Comma-separated TikTok post ids (providerId from GET /api/v1/posts, or postIds from a publish status), at most 20. |

A post that has barely been watched may have no `reach` or watch metrics yet;
those come back `null` or empty. `coverImageUrl` is a signed TikTok URL that
expires, so fetch it again rather than storing it. TikTok stops updating a
post's figures 365 days after it is published.

**Errors** — `401 unauthorized`, `400 invalid_request`, `404 account_not_found`,
`404 profile_not_found`, `422 connection_expired` (also returned when the
connection lacks `video.insights`), `422 provider_not_configured`,
`429 rate_limited`, `502 provider_error`.

## Request examples

**cURL**

```bash
curl --fail-with-body "https://app.tryadeli.com/api/v1/analytics/tiktok/video-insights?accountId=00000000-0000-4000-8000-000000000003&videoIds=6990565363377392901" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/analytics/tiktok/video-insights?accountId=00000000-0000-4000-8000-000000000003&videoIds=6990565363377392901", {
  headers: {
    Authorization: `Bearer ${process.env.ADELI_API_KEY}`,
  },
});
console.log(await response.json());
```

**Python**

```python
import os

import requests

response = requests.get(
    "https://app.tryadeli.com/api/v1/analytics/tiktok/video-insights",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "accountId": "00000000-0000-4000-8000-000000000003",
        "videoIds": "6990565363377392901",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "tiktok",
  "accountId": "00000000-0000-4000-8000-000000000003",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "videos": [
    {
      "id": "6990565363377392901",
      "mediaType": "VIDEO",
      "isAd": false,
      "caption": "little coco",
      "coverImageUrl": "https://p16-sign-va.tiktokcdn.com/...",
      "shareUrl": "https://www.tiktok.com/@creator/video/6990565363377392901",
      "embedUrl": "https://www.tiktok.com/player/v1/6990565363377392901",
      "durationSeconds": 20,
      "likeCount": 10, "commentCount": 2, "shareCount": 0, "favoriteCount": 1,
      "viewCount": 1231, "reach": 154,
      "createdAt": "2021-07-30T04:03:55.000Z",
      "insights": {
        "totalTimeWatchedSeconds": 695.9,
        "averageTimeWatchedSeconds": 4.1,
        "fullVideoWatchedRate": 0.0237,
        "newFollowers": 2,
        "profileViews": 9,
        "retention": [{ "second": "1", "percentage": 0.82 }],
        "impressionSources": [{ "key": "For You", "percentage": 0.8983 }],
        "audienceGenders": [], "audienceCountries": [{ "key": "US", "percentage": 0.7574 }],
        "audienceCities": [], "audienceTypes": []
      }
    }
  ],
  "fetchedAt": "2026-09-29T12:00:00.000Z"
}
```

### 422

```json
{
  "error": {
    "code": "connection_expired",
    "message": "TikTok connection requires reconnecting"
  }
}
```