---
title: "Recent events"
method: GET
path: "/api/v1/events"
tags: ["Events"]
---

# Recent events

`GET /api/v1/events`

## Request

- Base URL: `https://everypage.co`
- URL: `https://everypage.co/api/v1/events`
- 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`)

Poll recent activity across your files. One stream per call via `type`: `view` (default), `download`, or `gate` (Pro). Newest first without `since`; ascending after the cursor with `since=<last id>`. Cursors are per stream - never reuse a view id on download or gate (`view`/`download` ids are 32-bit; `gate` ids are 64-bit; there is no `type=all`). `file=` narrows to one file (UUID or short id; unknown = `[]`). Scope `readership:read`.
Note: the `download` stream records every explicit download, including your own - unlike the `file.downloaded` webhook, which only fires for non-owner downloads.

## Query parameters

- `type` 'view' | 'download' | 'gate'
- `file` string
- `since` integer
- `limit` integer

## Response `200`

Events (newest first without `since`; ascending from the cursor with it)

- ReadEvent[]
  - `id` integer: Stable event id for polling/dedup. Per-stream: not comparable across `type` values.
  - `fileUuid` string, uuid
  - `fileName` string
  - `readAt` string, date-time
  - `country` string: Absent on gate events.
  - `pagesViewed` integer: view events only (always present there, 0 included); absent on download/gate events.
  - `timeMs` integer: Time spent reading, milliseconds. view events only; absent on download/gate events.
  - `type` 'view' | 'download' | 'gate': Which stream the event belongs to.
  - `fields` object: gate events only: the submitted form fields (e.g. email, name).

## Other responses

- `400`: Unknown `type`.
- `401`: No or invalid API key, OAuth token, manage token or claim token (code `missing_token` or `invalid_token`).
- `403`: `type=gate` requires the Pro plan. NOTE: this plan check returns a plain-text message ("This feature requires the pro plan or higher"), a different 403 body than the `insufficient_scope` message an OAuth token missing `readership:read` receives.
- `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)