---
title: "Audience insights (any platform)"
method: GET
path: "/uploadposts/audience"
tags: ["Platform Integration"]
---

# Audience insights (any platform)

`GET /uploadposts/audience`

Who follows a connected account, when they are online, what they tap on the profile and how it compares to its category. One endpoint per QUESTION with a `platform`, exactly like /uploadposts/comments and /uploadposts/post-analytics — never one URL per network. Only `tiktok` answers today; any other value returns 400 with error_code `platform_not_supported` and a message naming the supported ones. `activity_by_hour` (24 entries, followers online per hour, summed over the window) is the field to build a publishing schedule on. The window is trimmed to what the platform accepts — at most 60 days, always ending before today — so read the `range` that comes back, not the one you sent. Requires the `profile_analytics` capability.

## Query parameters

- `platform` 'tiktok', required
- `user` string, required
- `start_date` string, date
- `end_date` string, date
- `benchmark_category` 'PERSONAL_BLOG' | 'MACHINERY_AND_EQUIPMENT' | 'HEALTH_AND_WELLNESS' | 'PETS' | 'AUTOMOTIVE_AND_TRANSPORTATION' | 'EDUCATION_AND_TRAINING' | 'FOOD_AND_BEVERAGE' | 'REAL_ESTATE' | 'ELECTRONICS' | 'SHOPPING_AND_RETAIL' | 'PUBLIC_ADMINISTRATION' | 'ART_AND_CRAFTS' | 'BABY' | 'GAMING' | 'RESTAURANTS_AND_BARS' | 'HOME_FURNITURE_AND_APPLIANCES' | 'PROFESSIONAL_SERVICES' | 'SOFTWARE_AND_APPS' | 'MEDIA_AND_ENTERTAINMENT' | 'BEAUTY' | 'SPORTS_FITNESS_AND_OUTDOORS' | 'CLOTHING_AND_ACCESSORIES' | 'TRAVEL_AND_TOURISM' | 'OTHERS' | 'FINANCE_AND_INVESTING'

## Response `200`

Audience insights.

- object
  - `success` boolean
  - `platform` string
  - `range` object — The window actually queried, after trimming. Render this one, not your input.
    - `start_date` string, date
    - `end_date` string, date
  - `audience` object — Follower distribution. Every percentage is a fraction of 1.
    - `countries` object[]
      - `country` string
      - `percentage` number — Fraction of 1, not a number out of 100.
    - `cities` object[]
      - `city` string
      - `percentage` number — Fraction of 1, not a number out of 100.
    - `ages` object[]
      - `age` string
      - `percentage` number — Fraction of 1, not a number out of 100.
    - `genders` object[]
      - `gender` string
      - `percentage` number — Fraction of 1, not a number out of 100.
  - `activity_by_hour` object[] — 24 entries, "0"-"23" in the account's local time, ordered numerically. Followers online in that hour, summed over the window.
    - `hour` string
    - `followers_online` integer
  - `followers_daily` object[] — One row per day, oldest first.
    - `date` string, date
    - `total` integer, nullable
    - `new` integer, nullable
    - `lost` integer, nullable
  - `profile_actions` object — Totals over the window for the profile's tappable elements. null means the platform reported nothing for this account — which is NOT the same fact as 0.
    - `bio_link_clicks` integer, nullable
    - `address_clicks` integer, nullable
    - `app_download_clicks` integer, nullable
    - `email_clicks` integer, nullable
    - `phone_number_clicks` integer, nullable
    - `lead_submissions` integer, nullable
  - `bio_description` string, nullable — The account's current bio text.
  - `benchmark_categories` string[] — The 25 values benchmark_category accepts. Always present, so a picker can be built without a second call.
  - `benchmark` object — Only when benchmark_category was sent. Only the metrics the platform actually returned are present.
    - `category` string
    - `average_comments` number
    - `average_engagement_rate` number — Fraction of 1.
    - `average_follower_count` number
    - `average_follower_growth` number
    - `average_likes` number
    - `average_shares` number
    - `average_video_count` number
    - `average_video_views` number

## Other responses

- `400` — That network cannot answer this question yet. Upload-Post is one endpoint per QUESTION with a `platform`, so the message names the platforms that can. Branch on the error_code, not on a hard-coded platform list: when the network is added, the same call starts returning data. Some endpoints carry the text in `error` instead of `message`.
- `401` — Unauthorized — Invalid or expired token.
- `404` — Not Found — Resource does not exist.
- `409` — The TikTok token expired and could not be refreshed; the account must be reconnected.
- `502` — TikTok rejected the request. Its message is returned verbatim.

## Changes

- **2026-08-31** `f3ef68b64fbc` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/upload-post/apis/upload-post-api/changes/uploadposts/audience/get.md)

---

[API](https://skmtc.dev/upload-post/apis/upload-post-api.md) · [All operations](https://skmtc.dev/upload-post/apis/upload-post-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/upload-post/upload-post-api/revisions/f3ef68b64fbc/schema)