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

# Audience Breakdown

> Sessions by country, city, browser, operating system or device.

Return the project's sessions in a window grouped by one dimension, as counts and percentages.

<Info>
  Scope: `read`.
</Info>

## Path parameters

<ParamField path="projectId" type="string" required>
  The project.
</ParamField>

## Query parameters

<ParamField query="dimension" type="string" default="country">
  `country`, `city`, `browser`, `os` or `device`.
</ParamField>

<ParamField query="country" type="string">
  With `dimension=city`: restrict to one country code, e.g. `DE`.
</ParamField>

<ParamField query="startDate" type="string">ISO 8601 start of the window.</ParamField>
<ParamField query="endDate" type="string">ISO 8601 end of the window.</ParamField>

## Headers

<ParamField header="x-api-key" type="string" required>
  Your Streampixel API key.
</ParamField>

## Response

<ResponseField name="dimension" type="string">The dimension used.</ResponseField>
<ResponseField name="total" type="number">Sessions in the window with a value for the dimension.</ResponseField>

<ResponseField name="breakdown" type="array">
  `value`, `count`, `percentage`; for cities also `country` and `countryCode`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={"dark"}
  curl "https://platform.streampixel.io/api/v1/analytics/projects/664f1a2b3c4d5e6f7a8b9c0d/analytics/breakdown?dimension=browser&startDate=2026-09-19T00:00:00Z&endDate=2026-09-26T00:00:00Z" \
    -H "x-api-key: $STREAMPIXEL_API_KEY"
  ```

  ```javascript Node.js theme={"dark"}
  const u = new URL('https://platform.streampixel.io/api/v1/analytics/projects/664f1a2b3c4d5e6f7a8b9c0d/analytics/breakdown');
  u.search = new URLSearchParams({ dimension: 'browser', startDate: '2026-09-19T00:00:00Z', endDate: '2026-09-26T00:00:00Z' });
  const { breakdown } = await (await fetch(u, { headers: { 'x-api-key': process.env.STREAMPIXEL_API_KEY } })).json();
  ```

  ```python Python theme={"dark"}
  import os, requests

  r = requests.get(
      "https://platform.streampixel.io/api/v1/analytics/projects/664f1a2b3c4d5e6f7a8b9c0d/analytics/breakdown",
      params={"dimension": "browser", "startDate": "2026-09-19T00:00:00Z", "endDate": "2026-09-26T00:00:00Z"},
      headers={"x-api-key": os.environ["STREAMPIXEL_API_KEY"]},
  )
  print(r.json()["breakdown"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={"dark"}
  {
    "success": true,
    "projectId": "664f1a2b3c4d5e6f7a8b9c0d",
    "dimension": "browser",
    "total": 143,
    "count": 4,
    "breakdown": [
      { "value": "Chrome", "count": 98, "percentage": 68.5 },
      { "value": "Safari", "count": 27, "percentage": 18.9 },
      { "value": "Edge", "count": 12, "percentage": 8.4 },
      { "value": "Firefox", "count": 6, "percentage": 4.2 }
    ]
  }
  ```
</ResponseExample>

## Errors

| Status | Cause                                                            |
| ------ | ---------------------------------------------------------------- |
| `400`  | Unknown `dimension`.                                             |
| `403`  | The key lacks `read`, or the project belongs to another account. |