Skip to main content
The Audit API lets enterprise organization admins read their organization’s stored audit events on a pull basis, alongside or instead of audit log webhooks. Point a SIEM collector or a scheduled job at a single endpoint, page through events newest-first, and poll on your own cadence. The API and webhooks are not identical; see Webhooks or API? for the differences.
The Audit API uses a dedicated audit log API key, separate from the Sonar API keys used for chat completions, search, and other developer endpoints. Sonar API keys cannot call this endpoint.

Prerequisites

  • An Enterprise organization with audit logging enabled. Org admins turn this on under Organization Settings → Data and privacy → Audit Log Settings. See the Audit logs help center article for eligibility and setup.
  • An organization admin to create and manage keys.
Audit logging must be on before you can create a key, and if it is later turned off the API returns 404 until it is re-enabled. Events are recorded only while audit logging is on, so there is no history from before you enabled it.

Create an audit log API key

  1. In the Perplexity web app, open your organization’s settings and go to Enterprise APIs.
  2. Under Audit API → Audit log API keys, select Create key, give the key a name you will recognize later (for example, SIEM production), and confirm.
  3. Copy the key immediately. The full key is shown only once; afterward the list shows only the key’s name and creation date.
  4. Store the key in a secrets manager and treat it like any other credential.
Key properties:
  • Scope. Keys are read-only and limited to the audit_logs:read scope. They cannot change settings, manage members, or call other Perplexity APIs.
  • Organization-bound. A key reads events for the organization it was created in and nothing else.
  • Revocation. Org admins can revoke a key from the same page. Revoked keys stop working immediately, and requests with a revoked key return 401.
  • Audited. Every successful read through the API produces an audit_events_accessed event in your audit log (see Access events).
If the Create key button is unavailable or you see “API key creation is unavailable for this organization,” contact your Perplexity account team to enable the Audit API for your organization.

Make a request

Send the key as a bearer token to GET https://api.perplexity.ai/v1/admin/audit-events.
Events are returned newest first. Without any time parameters, the endpoint covers the most recent 30 days.

Query parameters

Cursors (first_id, last_id, after_id, before_id) are opaque strings. Store them and pass them back unchanged; do not parse them or build your own.

Response

Event fields

Metadata can hold recorded content, not only identifiers: for example, query text for query events, answer text for answer_generated events, and file names for file_upload events. Query text is limited to the first 500 characters. Answer text (answer in answer_generated and response in computer_task_completed) can be up to 32,000 characters through the API, while webhooks deliver only the first 500. Older events may hold only the first 500 characters. The API redacts credentials in organization_settings_update events for the audit log webhook settings. Authorization token values are replaced with [REDACTED], and webhook URLs keep only the destination origin. Cleared values remain identifiable as cleared. This redaction applies to API responses only, not to webhook deliveries, and it does not remove other recorded content from metadata.

Paginate and poll

Audit events are append-only and ordered by created_at. The patterns below work well for a scheduled collector.

Backfill a time window

Fix start_time and end_time for the whole run, then follow last_id until has_more is false.
Each request can cover at most 30 days. Split longer ranges into consecutive 30-day windows.

Poll for new events

For ongoing collection, keep a checkpoint and ask for events newer than it:
  1. On each cycle, capture the current time as end_time and keep it fixed for every page in that cycle.
  2. Pass the checkpoint you saved from the previous cycle as before_id. Each response holds the next batch of newer events, newest first.
  3. While has_more is true, pass that page’s first_id as before_id for the next request. Keep paging forward with before_id only; sending after_id as well returns 400.
  4. Store the last page’s first_id as the next checkpoint. If data was empty, keep the old checkpoint.
On the first run there is no checkpoint yet, so page backward from end_time with after_id and last_id, as in a backfill, and save the first page’s first_id as the checkpoint.
The API has no guaranteed freshness interval. Events are stored separately from webhook delivery and can become readable some time after they occur. Poll every few minutes rather than continuously. An event that is stored late keeps its original created_at, so a checkpoint that has already advanced past that time does not return it. To catch late arrivals, periodically re-read a recent window with start_time and end_time, and deduplicate on id. A checkpoint must fall inside the requested time range, and start_time defaults to 30 days before end_time. If your collector has been stopped for longer than that, the saved checkpoint is rejected with 400. Backfill the gap in 30-day windows, then use the first_id from the first page of the most recent window as the new checkpoint.

Access events

Every successful read through the Audit API is itself recorded as an audit_events_accessed event. These events are system-generated, so actor_email, ip_address, and user_agent are empty and session_id is null. The metadata identifies the key and the request:
These events are available only through the API; they are not delivered to webhooks. So that a collector does not generate a feed that is mostly its own reads, the default response omits audit_events_accessed events. Request them explicitly with event_type=audit_events_accessed when you want to review who has been reading your audit log.

Rate limits and errors

Each organization may make up to 2 requests per second to this endpoint across all of its audit log API keys. Requests beyond that return 429 with a Retry-After header; wait at least that long before retrying. Use limit=500 to minimize the number of calls needed. Errors use the standard API error envelope:
Every attempt, including rejected ones, is logged on Perplexity’s side for security review.

Webhooks or API?

Webhooks and the API report the same activity, but their payloads are not identical, and neither is a guaranteed complete copy of the other. Use whichever fits your tooling, or both:

Differences between the two

If you consume both, or move from one to the other, account for these differences:
  • Top-level field names. The event envelope uses different names in each (see the table below). The metadata object is shared, subject to the exceptions in this list.
  • Credential redaction. The API redacts webhook authorization tokens and webhook URLs in organization_settings_update events. Webhook deliveries are not redacted.
  • comet_agent_action. API metadata contains only action, when recorded. The url and action_params fields are sent only through webhooks and are not stored for API retrieval.
  • audit_events_accessed. Each successful API read creates this event. It is available only through the API.
  • Answer text length. The API can return up to 32,000 characters of answer text. Webhooks deliver the first 500.
  • Completeness. Events are stored for the API separately from webhook delivery, and failed webhook deliveries are not retried. An event can be present in one and missing from the other.
The Audit API is distinct from the Analytics API, which reports Computer usage and uses its own organization analytics API key.