# TikTok account insights

> Daily metrics and follower demographics for a TikTok account.

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

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

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

Returns the account's daily metrics and follower demographics for a window of
complete UTC days. Needs the `user.insights` permission, which every
connection made since Adeli moved to TikTok API for Business has granted.

**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.                          |
| `startDate` | `YYYY-MM-DD` |          | First day, UTC. At most 60 days ago. Give both dates or neither; the default is the last 28 complete days. |
| `endDate`   | `YYYY-MM-DD` |          | Last day, UTC, before today and on or after startDate.                                                     |

> **Note: null means TikTok did not report it**
>
> TikTok's daily figures lag by 24 to 48 hours and exist only while Analytics is
> turned on in the TikTok app. Unique views, follower gains and losses, engaged
> audience, and `activity` are reported for Business Accounts only; the click
> metrics need a verified or registered business; demographics and `activity`
> need at least 100 followers. Anything TikTok withholds is `null` or an empty
> list, never `0`.

`activity` is when followers were active, by hour. `percentage` values are
fractions of 1.

**Errors** — `401 unauthorized`, `400 invalid_request`, `404 account_not_found`,
`404 profile_not_found`, `422 connection_expired` (also returned when the
connection lacks `user.insights`; reconnecting fixes it),
`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/account-insights?accountId=00000000-0000-4000-8000-000000000003&startDate=2026-09-01&endDate=2026-09-28" \
  -H "Authorization: Bearer $ADELI_API_KEY"
```

**JavaScript**

```javascript
const response = await fetch("https://app.tryadeli.com/api/v1/analytics/tiktok/account-insights?accountId=00000000-0000-4000-8000-000000000003&startDate=2026-09-01&endDate=2026-09-28", {
  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/account-insights",
    headers={"Authorization": f"Bearer {os.environ['ADELI_API_KEY']}"},
    params={
        "accountId": "00000000-0000-4000-8000-000000000003",
        "startDate": "2026-09-01",
        "endDate": "2026-09-28",
    },
)
print(response.json())
```

## Responses

### 200

```json
{
  "platform": "tiktok",
  "accountId": "00000000-0000-4000-8000-000000000003",
  "profileId": "00000000-0000-4000-8000-000000000001",
  "isBusinessAccount": true,
  "startDate": "2026-09-01",
  "endDate": "2026-09-28",
  "daily": [
    {
      "date": "2026-09-01",
      "videoViews": 1126, "uniqueVideoViews": 900, "profileViews": 40,
      "likes": 26, "comments": 4, "shares": 1,
      "followers": 1204, "newFollowers": 6, "lostFollowers": 2, "engagedAudience": 120,
      "bioLinkClicks": 3, "emailClicks": 0, "phoneNumberClicks": 0, "addressClicks": 0,
      "appDownloadClicks": 0, "leadSubmissions": 0,
      "activity": [{ "hour": "18", "count": 52 }]
    }
  ],
  "audience": {
    "ages": [{ "key": "18-24", "percentage": 0.42 }],
    "genders": [{ "key": "Female", "percentage": 0.6 }],
    "countries": [{ "key": "US", "percentage": 0.75 }],
    "cities": [{ "key": "Austin", "percentage": 0.08 }]
  },
  "fetchedAt": "2026-09-29T12:00:00.000Z"
}
```

### 400

```json
{
  "error": {
    "code": "invalid_request",
    "message": "endDate must be before today (UTC); TikTok reports complete days only",
    "details": [
      {
        "code": "custom",
        "message": "endDate must be before today (UTC); TikTok reports complete days only",
        "path": ["endDate"]
      }
    ]
  }
}
```

### 422

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