> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# About the Events API beta

The 1Password Events API v3 (version 3) beta is a REST-style HTTP API that follows the [OpenAPI 3.0 <Icon icon="arrow-up-right-from-square" />](https://spec.openapis.org/oas/latest.html) specification. All requests are made over HTTPS and return JSON responses.

The beta introduces a [new v3 versioned endpoint](/events-api/beta/reference/get-v3-auditevents):

* `GET /api/v3/auditevents`

This endpoint returns audit events for actions performed by team members in a 1Password account. Each event describes:

* Who performed the action (the actor).
* What was affected (one or more target entities).
* Where and how the action occurred (context about the account, location, client, device, and session).

The beta API can be used alongside the existing Events API. The v1 and v2 endpoints for audit events, item usages, and sign-in attempts remain available.

## Request methods

The beta API currently supports a single HTTP method (GET) to retrieve audit events and uses query parameters for pagination and time filters.

The `/api/v3/auditevents` beta endpoint uses GET with query parameters for pagination and time filters.

<Note>
  The v1 and v2 API endpoints continue to use POST requests with a cursor object in the request body.
</Note>

## Servers and URLs

The v3 beta endpoint is currently hosted on the same Events API servers as the production API. Your base URL depends on the [region](https://support.1password.com/regions/) where your 1Password account is hosted:

| If your account is hosted on: | Your base URL is:                  |
| ----------------------------- | ---------------------------------- |
| `1password.com`               | `https://events.1password.com`     |
| `ent.1password.com`           | `https://events.ent.1password.com` |
| `1password.ca`                | `https://events.1password.ca`      |
| `1password.eu`                | `https://events.1password.eu`      |

To call the beta endpoint, append the v3 path to your base URL:

```text theme={null}
$BASE_URL/api/v3/auditevents
```

All requests must be made over HTTPS.

<Note>
  It's possible these servers could change during the beta or when the v3 endpoint moves to production. You can use the [Events API beta roadmap and changelog](/events-api/beta/roadmap) to track changes.
</Note>

## Endpoints

The v3 beta API uses the following endpoint:

* [`GET /api/v3/auditevents`](/events-api/beta/reference/get-v3-auditevents): Retrieve audit events for actions performed by team members within a 1Password account.

Item usage and sign-in attempt events remain available through the existing v1 and v2 endpoints.

## Authorization

All calls to the v3 beta endpoint must be authorized with a valid [JWT-encoded <Icon icon="arrow-up-right-from-square" />](https://datatracker.ietf.org/doc/html/rfc7519) bearer token in the [`Authorization` header](#request-headers). The token must be scoped to include audit events.

## Request headers

Requests to the beta endpoint require the `Authorization` header:

```shell theme={null}
Authorization: Bearer $EVENTS_API_TOKEN
```

If your bearer token is missing, malformed, or invalid, the API will return a `401 Unauthorized` response.

## Pagination

The beta API uses cursor-based pagination passed in the query string.

### Query parameters

The v3 `auditevents` endpoint accepts the following optional query parameters:

* `max_page_size`: The maximum number of events to return in a single response. If you don't include `max_page_size`, or if you set it to `0`, the server default of `100` is used. The endpoint accepts any positive value, but it returns no more than `1000` events per page.

* `start_time`: The earliest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly greater than this value are returned. Invalid if `page_token` is specified.

* `end_time`: The latest insertion time for which to retrieve events (exclusive), filtered on when events were ingested by 1Password. Only events whose insertion time is strictly less than this value are returned. Invalid if `page_token` is specified.

* `page_token`: An opaque string that identifies the next page of results to retrieve.

<Note>
  Data collection for the `/api/v3/auditevents` beta endpoint started December 1, 2025. To access event data prior to that date, you'll need to use the [`/api/v2/auditevents` production endpoint](/events-api/reference/audit-events).
</Note>

### Response metadata

Every `200` successful response includes the `audit_events` array at the top level. If there are more pages of events to retrieve, the response will also include a `next_page_token` you can pass to the next request.

When the response includes a `next_page_token`, use that token in the `page_token` query parameter of your next request. You can continue making requests until there are no more events.

If a response doesn't include a token, that indicates there are no more pages of results to retrieve.

### Pagination workflow

The following example shows a typical pagination workflow:

1. Initial request: Make a GET call to `/api/v3/auditevents` with any combination of `max_page_size`, `start_time`, and `end_time` parameters you need. Note that data collection for this endpoint started December 1, 2025.

2. Check the response: Process the `audit_events` array. Check for a `next_page_token` at the top level of the response to see if there are more pages. If there's a token, continue to step 3.

   If there's an empty `audit_events` array with no `next_page_token`, that means there are no new events yet. Wait and poll again.

3. Subsequent requests: If there are more pages of events, call the endpoint again using the value of the `next_page_token` in the `page_token` query parameter of your next request. For example:

   ```shell theme={null}
   curl --request GET \
   	--url "https://events.1password.com/api/v3/auditevents?page_token=eyJQYWdlU2l6ZSI6NSwiU3RhcnRUaW1lIjoiMjAyNS0xMC0wMVQwMDowMDowMFoiLCJFbmRUaW1lIjoiMjAyNi0wMS0wNlQyMTozMzo0Ny44NDA2MjA3NFoiLCJTZWFyY2hBZnRlciI6MTc2MzA2MjYxMjQ0MCwiVGllQnJlYWtlciI6IkpaUjdaNDNMN1ZGVDVLVE0zRURBRURSRlBRIn0" \
   	--header "Authorization: Bearer $EVENTS_API_TOKEN"
   ```

   Repeat this process until the response no longer includes a `next_page_token`, which means you've received all events for the requested time window.

To keep receiving new events as they arrive, see [continuous polling](#continuous-polling).

<Warning>
  Do not use the `start_time` or `end_time` query parameters in a request that also uses the `page_token` query parameter. Doing so will result in a `400` bad request error.
</Warning>

### Continuous polling

You can use continuous polling with your integration to call the endpoint on a regular schedule. This allows the integration to retrieve new events as they become available and keep your copy of audit events continuously up to date.

To continue the polling loop after the initial pagination is complete:

1. Record the `insert_time` of the last event in the response.

2. Wait until the next scheduled check for new events (the polling interval you set up in your integration).

3. Make a new request using the recorded `insert_time` as the `start_time` parameter. For example:

   ```shell theme={null}
   curl --request GET \
   	--url "https://events.1password.com/api/v3/auditevents?start_time=2026-05-29T18:36:31.883698939Z" \
   	--header "Authorization: Bearer $EVENTS_API_TOKEN"
   ```

4. Process the events in the response. If the response includes a `next_page_token`, continue the [pagination workflow](#pagination-workflow) using the `page_token` query parameter. Otherwise, record the `insert_time` of the last event in the response and repeat this loop with that value as your new `start_time`.

No deduplication of the boundary event is required when polling.

## Timestamps

Every audit event includes two date and time fields, both in [RFC 3339 format: <Icon icon="arrow-up-right-from-square" />](https://datatracker.ietf.org/doc/html/rfc3339)

* `create_time`: When the event occurred.
* `insert_time`: When the event was received and stored by 1Password.

The `start_time` and `end_time` query parameters filter on `insert_time`, not `create_time`. This means a single response can include events whose `create_time` falls outside the query window, as long as the events were ingested within it. This is most likely to happen for events that take time to reach 1Password, such as those from offline clients that sync later.

Because the endpoint filters on `insert_time`, events that arrive later will surface in the next poll that uses a `start_time` strictly before their `insert_time`. Your [continuous polling](#continuous-polling) loop will receive these events without any special handling.

## Rate limits

Requests to the beta endpoint are rate limited to:

* 600 requests per minute
* 30,000 requests per hour

The API uses standard HTTP headers to communicate your current rate limit window and remaining quota. Responses from `GET /api/v3/auditevents` may include the following headers:

* `RateLimit-Limit`: The total number of requests allowed for the current time window.
* `RateLimit-Remaining`: How many requests you can still make in the current window.
* `RateLimit-Reset`: The Unix timestamp (in seconds) that indicates when the current rate limit window will reset.

If you exceed the allowed rate, the API returns a `429 Too Many Requests` response. The `429` response includes the following header:

* `Retry-After`: Indicates how many seconds to wait before making another request.

When you receive `429 Too Many Requests`, you should:

1. Stop sending additional requests to the endpoint.
2. Wait for the number of seconds specified in the `Retry-After` header.
3. Resume requests, ideally with backoff and retry logic in your client.