Accounts & connections · Accounts

Get follower stats

Fetches follower stats.

GEThttps://api.pozy.ai/v1/accounts/follower-stats

getFollowerStats

Request

Send your API key as Authorization: Bearer pz_live_.... Read-only keys can call it. Keys with the analytics resource group disabled get 403 resource_group_disabled. Authentication

Query parameters

Name	Type	Notes
`accountIds`	string
`profileId`	string
`fromDate`	string (date)
`toDate`	string (date)
`granularity`	string	One of `daily`, `weekly`, `monthly`Default `daily`
`limit`	integer	1 to 25
`cursor`	string

Example

curl -X GET "https://api.pozy.ai/v1/accounts/follower-stats?limit=1" \
  -H "Authorization: Bearer $POZY_API_KEY"

const res = await fetch("https://api.pozy.ai/v1/accounts/follower-stats?limit=1", {
  headers: { Authorization: `Bearer ${process.env.POZY_API_KEY}` },
});
const data = await res.json();
if (!res.ok) throw new Error(data?.error ?? `Request failed with status ${res.status}`);
console.log(data);

import os
import requests

resp = requests.get(
    "https://api.pozy.ai/v1/accounts/follower-stats",
    headers={"Authorization": f"Bearer {os.environ['POZY_API_KEY']}"},
    params={
        "limit": 1,
    },
    timeout=30,
)
resp.raise_for_status()
print(resp.json())

Response

200 on success

accountsarray of object
25 child fields
- _idstringrequired
- platformstringrequired
  One of tiktok, instagram, facebook, youtube, linkedin, twitter, threads, pinterest, reddit, bluesky, googlebusiness, telegram, snapchat, discord, slack, whatsapp, shopify, wordpress, wix, linkedinads, metaads, pinterestads, tiktokads, xads and 15 more.
- profileIdstring or objectrequired
  One of:
  string
  Profile (11 fields)
  _idstring
  userIdstring
  namestring
  descriptionstring
  colorstring
  timezonestring
  Can be null.
  externalIdstring
  Can be null.
  isDefaultboolean
  isOverLimitboolean
  accountCountinteger
  createdAtstring (date-time)
- usernamestring
- displayNamestring
- platformUserIdstring
- scopeAreasarray of string
  Can be null.
- oauthAppIdstring
  Can be null.
- tiktokAccountTypestring
  One of business, personal, unknown.
- profilePicturestring
  Can be null.
- profileUrlstring
- isActivebooleanrequired
- needsReconnectionboolean
- followersCountnumber
- followersLastUpdatedstring (date-time)
- parentAccountIdstring
  Can be null.
- enabledboolean
- rateLimitedUntilstring (date-time)
  Can be null.
- metadataobject
- currentFollowersnumber
- lastUpdatedstring (date-time)
- growthnumber
- growthPercentagenumber
- dataPointsnumber
- accountStatsobject
  11 child fields
  followingCountnumber
  mediaCountnumber
  videoCountnumber
  tweetCountnumber
  postsCountnumber
  pinCountnumber
  totalViewsnumber
  likesCountnumber
  monthlyViewsnumber
  listedCountnumber
  boardCountnumber
statsmap of array of object
dateRangeobject
- fromstring (date-time)
- tostring (date-time)
granularitystring
paginationobject
- limitintegerrequired
- nextCursorstringrequired
  Can be null.

200 response

{
  "accounts": [
    {
      "_id": "635d87e261ae344ef27fd1df",
      "platform": "tiktok",
      "profileId": "6a0b6573846efc28aaa9a3ff",
      "username": "acme",
      "displayName": "Acme",
      "platformUserId": "60c5beb6ca4037bb9ff5117a",
      "scopeAreas": [
        "string"
      ],
      "oauthAppId": "629a39de8c0a63af5a05067c",
      "tiktokAccountType": "business",
      "profilePicture": "string",
      "profileUrl": "https://pozy.ai/media/example-1.jpg",
      "isActive": true,
      "needsReconnection": true,
      "followersCount": 12.5,
      "followersLastUpdated": "2026-10-02T09:00:00.000Z",
      "parentAccountId": "6ce971ffa48fe63468db336b",
      "enabled": true,
      "rateLimitedUntil": "2026-10-02T09:00:00.000Z",
      "metadata": {},
      "currentFollowers": 12.5,
      "lastUpdated": "2026-10-02T09:00:00.000Z",
      "growth": 12.5,
      "growthPercentage": 12.5,
      "dataPoints": 12.5,
      "accountStats": {
        "followingCount": 12.5,
        "mediaCount": 12.5,
        "videoCount": 12.5,
        "tweetCount": 12.5,
        "postsCount": 12.5,
        "pinCount": 12.5,
        "totalViews": 12.5,
        "likesCount": 12.5,
        "monthlyViews": 12.5,
        "listedCount": 12.5,
        "boardCount": 12.5
      }
    }
  ],
  "stats": {
    "key": [
      {
        "date": "2026-10-02T09:00:00.000Z",
        "followers": 12.5
      }
    ]
  },
  "dateRange": {
    "from": "2026-10-02T09:00:00.000Z",
    "to": "2026-10-02T09:00:00.000Z"
  },
  "granularity": "string",
  "pagination": {
    "limit": 1,
    "nextCursor": "string"
  }
}

Errors

Errors use one shape: { error, type, code, param?, details? }. The ones you are most likely to see here:

400	invalid_request_error	A parameter or body field is missing or invalid. `param` names it.
401	authentication_error	The API key is missing, revoked or expired.
403	permission_error	The key is scoped to other profiles or has this resource group disabled.
429	rate_limit_error	Too many requests this minute. Wait for `Retry-After` seconds.

Every code is listed in Errors.

Request

Query parameters

Example

Response

Errors

More in Accounts