> ## 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. # Events API conventions Every request to the 1Password Events API follows the conventions on this page. To authenticate your requests, see [Authorization](https://www.1password.dev/events-api/authorization.md). ## Servers and base URLs The API service ID (`events`) and the server that hosts your 1Password account form the base URL you'll use for the API endpoints. | 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` | ## Endpoints ### Endpoint structure Each API endpoint starts with a [base URL](#servers-and-base-urls), followed by the resource or operation path: ```text theme={null} base_url/path ``` Replace the `base_url` placeholder with the appropriate base URL for your 1Password account and use the `path` of the operation or resource you want to access: [`introspect`](https://www.1password.dev/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect), [`auditevents`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fauditevents), [`itemusages`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fitemusages), or [`signinattempts`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fsigninattempts). For example, if your 1Password account is hosted on `ent.1password.com` and you want to retrieve a list of audit events, you would use the following URL to make a call to the `auditevents` endpoint: ```http Structure of an API endpoint theme={null} https://events.ent.1password.com/api/v2/auditevents ``` ### Endpoint versions The Events API supports both V1 and V2 endpoints for audit events, item usages, and sign-in attempts. The V2 endpoints in this reference provide additional information about users and accounts for managed service providers (MSPs). V1 endpoints remain fully supported for existing integrations that don't require the additional MSP account and user type information. Choose the appropriate version based on your needs: * Use V2 endpoints if you need MSP-related event data or if you're just starting with the Events API. * Use V1 endpoints if you have existing integrations and you don't require the additional MSP data. See the [API changelog](https://www.1password.dev/events-api/changelog.md) to learn more about the changes in the V2 endpoints and previous versions of the API. ## Request methods The Events API accepts the following standard HTTP request methods: * GET requests to the [`introspect`](https://www.1password.dev/events-api/reference#get-%2Fapi%2Fv2%2Fauth%2Fintrospect) endpoint return information about the events a bearer token has access to and the account where the token was issued. * POST requests to the [`auditevents`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fauditevents), [`itemusages`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fitemusages), and [`signinattempts`](https://www.1password.dev/events-api/reference#post-%2Fapi%2Fv2%2Fsigninattempts) endpoints return information about various activities in a 1Password account. Depending on which endpoint is called, the request returns one of the following: * Successful and failed attempts to sign in to a 1Password account. * Information about every use of an item stored in a shared vault in the account. * Audit events for actions performed by team members in the account. ## Request headers Requests to the Events API must include the correct header(s): * `Authorization`: Each GET and POST request to the Events API must be [authorized with a bearer token](https://www.1password.dev/events-api/authorization.md) scoped to access event data for that feature. You'll include your token in the authorization header. * `Content-Type`: Each POST request requires a `Content-Type` header to indicate the media type of the resource being sent in the request body. All data for the Events API is sent and received as JSON, so you'll need to specify `application/json` as the content type. GET requests don't contain a request body and therefore don't require this header. An example of a request header: ```text theme={null} Authorization: Bearer YOUR_BEARER_TOKEN Content-type: application/json ``` ## Pagination The Events API uses cursor-based pagination, which is useful for working with large datasets. In response to each request, the API returns a unique ID (cursor) that indicates where you left off retrieving data. On the next call, you can provide that cursor to continue fetching events starting from the next point in the dataset so no records are missed. There are two types of cursors used in calls to the API: a [reset cursor](#reset-cursor) and a [cursor](#cursor) (also called a continuing cursor). ### Reset cursor A reset cursor is used for the first request you make to the API to create a new point from which to start fetching data. You can also use a reset cursor any time you need to reset the parameters of your cursor – such as the number of records to return with each request – or go back to an earlier point in the records. For the first POST request you make to the API, you must include a `ResetCursor` object with an optional start time, end time, and limit parameters in the request body. The return will include a `cursor` in the response body that you can save to use in the next call made to the API. If no parameters are provided, the API will use the default values indicated in the schema. For example: > [tab] Example reset cursor request > > ```json theme={null} > { > "limit": 100, > "start_time": "2023-03-15T16:32:50-03:00", > "end_time": "2023-03-15T17:32:50-03:00" > } > ``` > [tab] ResetCursor object schema > > | Name | Type | Description | > | - | - | - | > | `limit`\* (optional)\* | number | The number of events to return in a single request. Specify a limit from 1 to 1000. If not specified, `limit` will default to 100. To return additional events, use the cursor position for subsequent requests. | > | `start_time`\* (optional)\* | string | The date and time to start retrieving events. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) If not specified, `start_time` will default to one hour before specified `end_time`. If no `end_time` is specified, `start_time` will default to one hour ago. | > | `end_time`\* (optional)\* | string | The date and time to stop retrieving events. Uses the [RFC 3339 standard.](https://datatracker.ietf.org/doc/html/rfc3339) | ### Cursor The `cursor` is a persistent checkpoint that marks your exact position in the event stream and remains valid across API sessions. For continued calling of the API, you should save the cursor you receive from each response. In your next call to the API, include the cursor from the previous response in the request body to start fetching data from the last indicated position. This allows you to resume from where you left off without missing any events. > [tab] Example cursor > > ```json theme={null} > { > "cursor": "aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK" > } > ``` > [tab] Cursor object schema > > | Name | Type | Description | > | - | - | - | > | `cursor` | string | Cursor to fetch more data, if available, or continue the polling process. Use the cursor returned in the response body of your previous to the endpoint. For example: `aGVsbG8hIGlzIGl0IG1lIHlvdSBhcmUgbG9va2luZyBmb3IK`. | The 1Password Events API apps for [Splunk](https://support.1password.com/events-reporting-splunk/) and [Elastic](https://support.1password.com/events-reporting-elastic/) will automatically store the `cursor` position for future requests. ## Rate limits The Events API has the following limits: * 600 requests per minute * 30,000 requests per hour Exceeding these limits will return the following error: ```text theme={null} 429 Too many requests ``` ## HTTP status codes Calls to the 1Password Events API may return the following HTTP status codes: | Code | Message | Description / Recommended action | | - | - | - | | `200` | OK | The request was successful and the server returned a JSON object or an array of objects. Recommended action: No action is required. | | `400` | Bad Request | The server could not understand the request due to invalid syntax. Recommended action: Check the [API reference](https://www.1password.dev/events-api/reference.md) and documentation [about the API](https://www.1password.dev/events-api/introduction.md) to make sure your request is properly formatted. | | `401` | Unauthorized | Authentication has failed or wasn't provided. Recommended action: Check that your request includes the [`Authorization` header](#request-headers), and make sure your bearer token is valid and scoped to access the requested resource. [Learn more about authorizing API requests.](https://www.1password.dev/events-api/authorization.md) | | `429` | Too Many Requests | The rate limit has been exceeded. Recommended action: Wait until the applicable rate-limit window (per-minute or per-hour) resets, then try again. [Learn more about Events API rate limits.](#rate-limits) | | `500` | Internal Server Error | The server encountered an unexpected condition that prevented it from fulfilling the request. Recommended action: Retry your request after a brief wait. If the issue persists, check the [1Password status page](https://status.1password.com/) to verify the Events API service is operational, or [contact 1Password Support](https://support.1password.com/contact/) for help. | ## Related topics - [API conventions](https://www.1password.dev/events-api/beta/conventions.md) - [1Password Events API v3 (beta)](https://www.1password.dev/events-api/beta.md) - [1Password Events API beta reference](https://www.1password.dev/events-api/beta/reference.md)