> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clipstake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audience and insights

> Country, age, and gender shares, daily account metrics, and how analytics access is scoped.

Analytics is a paid add-on. Two endpoints are dedicated to it, and several
other responses carry analytics fields when access is enabled.

## Audience breakdown

`GET /accounts/{username}/audience` returns the account's audience by country,
age bucket, and gender.

```bash theme={null}
curl --get "https://api.clipstake.com/v1/accounts/creator_handle/audience" \
  --header "Authorization: Bearer $CLIPSTAKE_API_KEY"
```

```json theme={null}
{
  "username": "creator_handle",
  "availability": "available",
  "as_of": "2026-09-19T03:12:00.000Z",
  "countries": [
    { "bucket": "US", "share_bps": 4120 },
    { "bucket": "GB", "share_bps": 1180 }
  ],
  "age": [{ "bucket": "18-24", "share_bps": 3900 }],
  "gender": [{ "bucket": "F", "share_bps": 5600 }]
}
```

Pass `as_of` with an ISO timestamp to read the breakdown as it stood then.
Snapshots are append-only, so an older reading stays available after a newer
one arrives.

### Shares are basis points, and they do not sum to 10000

`share_bps` is hundredths of a percent. 4120 is 41.20%.

Instagram reports only an account's top countries, so the shares routinely sum
to less than 10000. The remainder is real: it is audience whose country was
never reported.

<Warning>
  Do not rescale the shares to sum to 100%. That invents reach that was never
  measured. Show the remainder as unattributed instead.
</Warning>

Bucket labels are passed through exactly as Instagram reports them, such as
`18-24`, `F`, and `U`.

### `availability` is its own answer

| Value         | Meaning                                                                                  |
| ------------- | ---------------------------------------------------------------------------------------- |
| `available`   | A breakdown was collected and is returned.                                               |
| `pending`     | The account is enrolled and no sweep has landed yet.                                     |
| `unavailable` | Instagram reports no demographics for this account. Small accounts are the usual reason. |
| `not_tracked` | Nothing is collecting for this account.                                                  |

"No data" is not an empty breakdown. Keep the two apart in your own storage,
or an account Instagram cannot describe becomes indistinguishable from one with
no audience.

## Daily account insights

`GET /accounts/{username}/insights` returns one point per day, with `views`,
`reach`, `profile_views`, and `followers_count`. Narrow it with `since` and
`until`.

Any of the metrics can be `null` for a day. As everywhere in this API, `null`
means Instagram did not report it, and `0` is a real reading.

## Media demographics

`GET /submissions` can include a `demographics` block per tracked media.

This is the connected **account's** audience over the media's first days, not
the audience of the media itself. Instagram reports demographics per
account, not per post. The block carries `window_start`, `window_end`, and `snapshot_count`, so
you can see the real span that was averaged and the divisor used.

## Access and history

Analytics has two separate gates, and both apply.

**Current access.** When analytics is disabled, the dedicated endpoints answer
`403` with the code `analytics_not_enabled`, and analytics fields are omitted
from other responses entirely. Basic account identity stays visible.

**Entitled intervals.** When analytics is enabled, you see observations from
every interval you were entitled to, including a trial and any payment grace.
Observations collected while analytics was off stay hidden, even after a later
purchase.

<Note>
  Collection is separate from access. Background collection continues without
  analytics purchased, so enabling it later starts showing data from the
  moment entitlement began, not from every reading ever taken.
</Note>