# Get follower stats

Fetches follower stats.

```http
GET https://api.pozy.ai/v1/accounts/follower-stats
```

- Area: Accounts & connections / Accounts
- Auth: Authorization: Bearer pz_live_...

## Query parameters

- `accountIds` (string)
- `profileId` (string)
- `fromDate` (string (date))
- `toDate` (string (date))
- `granularity` (string): one of daily, weekly, monthly
- `limit` (integer)
- `cursor` (string)

## Example request

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

```ts
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);
```

```python
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

- `accounts`, array of object
  - `_id`, string, required
  - `platform`, string, required: 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
  - `profileId`, string or object, required
    - one of: string
    - one of: Profile
      - `_id`, string
      - `userId`, string
      - `name`, string
      - `description`, string
      - `color`, string
      - `timezone`, string: Can be null
      - `externalId`, string: Can be null
      - `isDefault`, boolean
      - `isOverLimit`, boolean
      - `accountCount`, integer
      - `createdAt`, string (date-time)
  - `username`, string
  - `displayName`, string
  - `platformUserId`, string
  - `scopeAreas`, array of string: Can be null
  - `oauthAppId`, string: Can be null
  - `tiktokAccountType`, string: One of `business`, `personal`, `unknown`
  - `profilePicture`, string: Can be null
  - `profileUrl`, string
  - `isActive`, boolean, required
  - `needsReconnection`, boolean
  - `followersCount`, number
  - `followersLastUpdated`, string (date-time)
  - `parentAccountId`, string: Can be null
  - `enabled`, boolean
  - `rateLimitedUntil`, string (date-time): Can be null
  - `metadata`, object
  - `currentFollowers`, number
  - `lastUpdated`, string (date-time)
  - `growth`, number
  - `growthPercentage`, number
  - `dataPoints`, number
  - `accountStats`, object
    - `followingCount`, number
    - `mediaCount`, number
    - `videoCount`, number
    - `tweetCount`, number
    - `postsCount`, number
    - `pinCount`, number
    - `totalViews`, number
    - `likesCount`, number
    - `monthlyViews`, number
    - `listedCount`, number
    - `boardCount`, number
- `stats`, map of array of object
- `dateRange`, object
  - `from`, string (date-time)
  - `to`, string (date-time)
- `granularity`, string
- `pagination`, object
  - `limit`, integer, required
  - `nextCursor`, string, required: Can be null

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