Historical Audits API

The historical audits endpoint is similar to the the Audits endpoint, but searches for audit records generated older than 12 calendar months ago. For searches of more recent data, the much more performant Audits API should be used.

The historical index should first be used to identify time-periods of interest, and then a search can be conducted to fetch the full details of the audit records from that period.

There are two important caveats to using this API:

  1. Searching through historical audits is an asynchronous operation. A search must first be created, and then the data may be consumed later
  2. Searching through historical audits imposes a stricter rate-limit than the general rate limit of the API. This API also enforces rate-limiting through a token-based system. a. Each Audits search consumes a specific number of tokens. The token cost of a search will be presented to the user through the read results operation. b. The token cost of a request is only known after the search completes, and corresponds to the amount of data which was required to be scanned to fulfill the request. Specifying additional filters, such as user_id, auditable_type, and audit_action will decrease the token cost. c. Upon making a request, the maximum token cost for a query will be charged to your account. The difference between the actual token cost and the maximum token cost will be refunded when the search completes and you read the search data. d. Tokens are continually replenished. You can see the current number of tokens available in the X-Historical-Tokens-Available header, present on every response to these resources. e. Reading from the historical index does not consume any tokens.

Select an API endpoint from the navigation to learn more.