> For the complete documentation index, see [llms.txt](https://developers.flipsnack.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.flipsnack.com/api-reference/collection.getreaderstats.md).

# collection.getReaderStats

Returns statistics for one reader of a specified flipbook.

**Note**:

* Requests must be made to **<https://api.flipsnack.com/v1>**.
* Only **GET** requests are accepted.

Use this method to retrieve statistics for one reader of a flipbook.

## Request parameters

| Name                        | Type    | Description                                                                                                                                                   |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `apiKey` (required)         | string  | The API key provided for your user. A missing key returns code `30`. An invalid key returns code `41`.                                                        |
| `signature` (required)      | string  | The request signature. See [How to sign a request](/how-to-sign-a-request.md). A missing signature returns code `30`. An invalid signature returns code `44`. |
| `action` (required)         | string  | The API method. Set this to `collection.getReaderStats`.                                                                                                      |
| `collectionHash` (required) | string  | The hash of the flipbook.                                                                                                                                     |
| `readerEmail`               | string  | Email address of a tracked reader.                                                                                                                            |
| `otpEmail`                  | string  | Email address of a reader authenticated through one-time password access.                                                                                     |
| `ssoViewerId`               | string  | Viewer ID for a reader authenticated through SSO.                                                                                                             |
| `trackableLinkHash`         | string  | Hash of the trackable link used by the reader.                                                                                                                |
| `linkId`                    | string  | ID of the trackable link used by the reader.                                                                                                                  |
| `startDate`                 | string  | First date in the reporting interval, formatted as `YYYY-MM-DD`.                                                                                              |
| `endDate`                   | string  | Last date in the reporting interval, formatted as `YYYY-MM-DD`.                                                                                               |
| `includePageBreakdown`      | boolean | When `true`, includes activity for each page. Default: `false`.                                                                                               |
| `includeLinkClicks`         | boolean | When `true`, includes link-click activity. Default: `false`.                                                                                                  |
| `includeSessionDetails`     | boolean | When `true`, includes session details. Default: `false`.                                                                                                      |

Provide exactly one reader identifier: `readerEmail`, `otpEmail`, `ssoViewerId`, `trackableLinkHash`, or `linkId`.

When both dates are omitted, the report covers 30 days inclusive: today in UTC and the preceding 29 days. When one date is omitted, the API sets the other date 29 days away. For spans longer than 1,825 days, the API keeps `endDate` and moves `startDate` forward. The response contains the effective date range.

## Response parameters

| Name                     | Type   | Description                                                                                                                                                                                                   |
| ------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `collectionHash`         | string | Hash of the requested flipbook.                                                                                                                                                                               |
| `reader.identifierType`  | string | Identifier type: `reader`, `otp`, `sso`, or `link`.                                                                                                                                                           |
| `reader.identifierValue` | string | Value of the reader identifier.                                                                                                                                                                               |
| `summary.impressions`    | number | Times the reader loaded the flipbook player.                                                                                                                                                                  |
| `summary.views`          | number | Times the reader interacted with the player.                                                                                                                                                                  |
| `summary.time_spent`     | number | Total viewing time in seconds.                                                                                                                                                                                |
| `summary.pages_read`     | number | Number of pages read by the reader.                                                                                                                                                                           |
| `summary.downloads`      | number | Times the reader downloaded the flipbook content.                                                                                                                                                             |
| `summary.clicks`         | number | Number of clicks made by the reader.                                                                                                                                                                          |
| `startDate`              | string | Effective start date, formatted as `YYYY-MM-DD`.                                                                                                                                                              |
| `endDate`                | string | Effective end date, formatted as `YYYY-MM-DD`.                                                                                                                                                                |
| `pageBreakdown`          | array  | Returned when `includePageBreakdown` is `true`. Includes every flipbook page, including pages with zero activity. Each item includes `page`, average `time_spent` in seconds per view, `clicks`, and `views`. |
| `linkClicks`             | array  | Returned when `includeLinkClicks` is `true`. Each item includes `page`, `targetUrl`, and `clicks`.                                                                                                            |
| `sessionDetails`         | array  | Returned when `includeSessionDetails` is `true`. Each item includes `firstViewedAt`, `lastActiveAt`, and `devices`.                                                                                           |

## Error codes

For complete list of error codes and messages go to [API status codes](/api-status-codes.md) section.

## Example

### Request

```bash
# GET
curl -X GET \
     -G \
     https://api.flipsnack.com/v1/ \
     -d action=collection.getReaderStats \
     -d apiKey=<YOUR-API-KEY> \
     -d collectionHash=<COLLECTION-HASH> \
     -d readerEmail=reader@example.com \
     -d includePageBreakdown=true \
     -d signature=<YOUR-REQUEST-SIGNATURE>
```

### Response

```json
{
  "code": 20,
  "status": "OK",
  "data": {
    "collectionHash": "d3m0h45h",
    "reader": {
      "identifierType": "reader",
      "identifierValue": "reader@example.com"
    },
    "summary": {
      "impressions": 12,
      "views": 8,
      "time_spent": 360,
      "pages_read": 4,
      "downloads": 1,
      "clicks": 2
    },
    "startDate": "2026-09-10",
    "endDate": "2026-10-09",
    "pageBreakdown": [
      {
        "page": 1,
        "time_spent": 40,
        "clicks": 2,
        "views": 3
      },
      {
        "page": 2,
        "time_spent": 30,
        "clicks": 0,
        "views": 2
      },
      {
        "page": 3,
        "time_spent": 0,
        "clicks": 0,
        "views": 0
      },
      {
        "page": 4,
        "time_spent": 60,
        "clicks": 0,
        "views": 1
      }
    ]
  }
}
```