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.
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
- In the Perplexity web app, open your organization’s settings and go to Enterprise APIs.
- 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. - Copy the key immediately. The full key is shown only once; afterward the list shows only the key’s name and creation date.
- Store the key in a secrets manager and treat it like any other credential.
- Scope. Keys are read-only and limited to the
audit_logs:readscope. 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_accessedevent 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 toGET https://api.perplexity.ai/v1/admin/audit-events.
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 bycreated_at. The patterns below work well for a scheduled collector.
Backfill a time window
Fixstart_time and end_time for the whole run, then follow last_id until has_more is false.
Poll for new events
For ongoing collection, keep a checkpoint and ask for events newer than it:- On each cycle, capture the current time as
end_timeand keep it fixed for every page in that cycle. - Pass the checkpoint you saved from the previous cycle as
before_id. Each response holds the next batch of newer events, newest first. - While
has_moreistrue, pass that page’sfirst_idasbefore_idfor the next request. Keep paging forward withbefore_idonly; sendingafter_idas well returns400. - Store the last page’s
first_idas the next checkpoint. Ifdatawas empty, keep the old checkpoint.
end_time with after_id and last_id, as in a backfill, and save the first page’s first_id as the checkpoint.
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 anaudit_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:
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 return429 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
metadataobject is shared, subject to the exceptions in this list. - Credential redaction. The API redacts webhook authorization tokens and webhook URLs in
organization_settings_updateevents. Webhook deliveries are not redacted. comet_agent_action. API metadata contains onlyaction, when recorded. Theurlandaction_paramsfields 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.