---
title: "A file's readership report"
method: GET
path: "/api/v1/files/{uuid}/readership"
tags: ["Events"]
---

# A file's readership report

`GET /api/v1/files/{uuid}/readership`

## Request

- Base URL: `https://everypage.co`
- URL: `https://everypage.co/api/v1/files/{uuid}/readership`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://everypage.co/oauth/authorize`, token URL `https://everypage.co/oauth/token`, scopes: `readership:read`)

The owner's readership dashboard data. The response shape follows the owner's plan (a `tier` field says which sections are present). On the Pro plan the response includes a `variants` array - per-link-variant readership: `{uuid, label, sessions, avgTimeMs, revoked, redacted}` per variant, label omitted after GDPR redaction. Scope `readership:read`.

## Response `200`

Readership report (plan-shaped; `variants` present on Pro when the file has link variants)

- ReadershipReport: The owner's readership dashboard data. `file`, `tier` and `summary` are always present; the other sections follow the OWNER's plan (`tier`): Basic adds `effectivePages`, `viewsOverTime`, `funnel`, `referrers`, `browsers`, `sources`, `viewerModes`, `peakTimes`, `devices` and `countries`; Pro adds per-viewer `sessions` (with `variants` when the file has link variants) and, when configured, `hotspotTaps` and `ctaTaps`. Sections above the plan are omitted, not empty.
  - `file` File, required: The owner's view of a file (`FileResponse`). Optional fields are omitted when empty rather than sent as null. `revisions` is populated only by the single-file GET, never in the list.
    - `uuid` string, uuid
    - `shortId` string: Short share-URL alias; absent on files created before short IDs.
    - `slug` string: Vanity link name (Pro); absent unless set. Resolves only on the owner's custom domain.
    - `originalName` string
    - `size` integer: Bytes
    - `mimeType` string
    - `createdAt` string, date-time
    - `updatedAt` string, date-time
    - `deleteAt` string, date-time: Absent when the file never expires.
    - `viewCount` integer
    - `totalPages` integer
    - `viewerMode` 'standard' | 'flipbook' | 'swipe' | 'magazine'
    - `protected` boolean: True if a password is set.
    - `allowDownload` boolean
    - `requireEmail` boolean
    - `notifyOnView` boolean
    - `commentsEnabled` boolean: Reader feedback notes are on (Pro to enable).
    - `commentsAllowPublic` boolean: Commenters may opt into public display of their note.
    - `notifyOnComment` boolean: The owner is emailed (throttled) when a note arrives.
    - `askReceipt` boolean: Viewers are asked to confirm receipt (Basic+ to enable).
    - `showExpiry` boolean: Readers see a live "Expires in" countdown next to Download (default true, every plan). When false the public share-link metadata omits the expiry instant entirely.
    - `marksEnabled` boolean: Proofing page marks are on (Pro to enable).
    - `annotationsEnabled` boolean: Proofing annotations are on (Pro to enable).
    - `viewLimit` integer: Self-destruct cap (Basic+). Absent when unlimited.
    - `viewsConsumed` integer: Views consumed against `viewLimit` (always present, 0 when no limit).
    - `burnedAt` string, date-time: Present once the view-limit sweep destroyed the blob; the row and its readership survive, and content replacement un-burns it.
    - `gateDomains` string[]: Email-gate domain allowlist (Pro). Absent when any domain is accepted.
    - `gateFields` GateField[]: The stored lead-capture form definition (Pro). Absent when the gate is the plain email prompt.
      - `key` string, required: Unique snake_case key; submitted values and captured responses are keyed by it.
      - `label` string, required
      - `type` 'text' | 'email' | 'phone' | 'company' | 'select', required: `select` is a drop-down: the viewer picks exactly one of `options`. Text, phone and company values are capped at 500 characters.
      - `required` boolean
      - `options` string[]: The drop-down choices (type `select` only; unique). Omitted for every other type.
    - `gateHeading` string: The owner's heading for the gate card readers see before the document opens (Pro). Absent when the default wording applies.
    - `gateMessage` string: The owner's explanatory line on the gate card (Pro). Absent when the default wording applies.
    - `watermark` boolean: Viewer pages are stamped with the reader identity (Pro).
    - `viewerSettings` object: The stored appearance/behaviour blob exactly as saved (see the FileSettings.viewerSettings description); `{}` when never customised. Always present for the owner regardless of current plan.
    - `shareDomain` string: The owner's verified Pro custom domain that share links and embeds are built on. Absent when links use everypage.co.
    - `folderId` string, uuid: UUID of the folder the file is filed in. Absent when unfiled.
    - `anonShareable` boolean: True for owner-less files that are public-by-link (browser anonymous uploads, Canva imports). Always false once claimed.
    - `revisions` Revision[]: Replacement history - superseded content versions, newest first. Populated only by GET /api/v1/files/{uuid}; absent in the list and when the content was never replaced.
      - `version` integer: The content version this entry was (1 = the original upload).
      - `originalName` string
      - `size` integer: Bytes
      - `totalPages` integer
      - `createdAt` string, date-time: When this version was uploaded.
    - `pageRange` PageRange: A non-owner page window, 1-based and inclusive. `{"from":0,"to":0}` is the explicit "no range" value (clears the file-level range; as a variant override it serves the full document through that variant).
      - `from` integer: First shared page (1-based).
      - `to` integer: Last shared page (inclusive; must be >= from).
    - `contentVersion` integer: Counts in-place content replacements (1 = the original upload).
    - `palette` string[]: Colour palette extracted from the document at import time: hex swatches ("#rrggbb"), dominant colour first, at most 6. ADVISORY ONLY - extraction is best-effort (first-page embedded raster images, short time budget), so the field is simply absent for vector-only documents, for files uploaded through non-import paths, for files created before the feature, and whenever extraction fails or times out. Absence is normal, never an error; use the palette for theming (e.g. styling a share card), never for logic.
    - `canvaDesignId` string: The Canva design this file was published from. Absent on files with no design binding (including after a detach).
    - `canvaUpdatesEnabled` boolean: Whether a Canva-side republish of the bound design may replace this file's bytes (see the setting). Present only alongside canvaDesignId.
  - `tier` 'free' | 'basic' | 'pro', required: The owner's plan, which decides which sections are present.
  - `summary` object, required
    - `totalViews` integer
    - `totalSessions` integer
    - `uniqueVisitors` integer
    - `uniqueCountries` integer
    - `avgTimeMs` integer
    - `downloads` integer
  - `variants` object[]: Pro only, when the file has link variants: per-variant readership.
    - `uuid` string, uuid
    - `label` string: Omitted after GDPR redaction.
    - `sessions` integer
    - `avgTimeMs` integer
    - `revoked` boolean
    - `redacted` boolean

## Other responses

- `401`: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
- `403`: Not the owner (code `forbidden`). Unlike most file routes this one does not hide foreign files behind 404.
- `404`: Unknown id, or a file you do not own on routes where 404 replaces 403 (code `not_found`).
- `429`: Over the limit - 120 requests per minute per Authorization value on /api/v1 (webhook test 10/min; the Canva lane 30/min per IP). Code `rate_limited`; wait for `Retry-After`.

---

[API](https://skmtc.dev/everypage/apis/everypage-api.md) · [All operations](https://skmtc.dev/everypage/apis/everypage-api/llms.txt) · [OpenAPI document](https://skmtc.dev/everypage/apis/everypage-api/revisions/e6674f903456?raw)