Audit Logs - Perplexity Help Center

Overview

Audit Logs are available to Enterprise organizations with 50 seats or more, or with at least one Enterprise Max seat. Administrators can use them to investigate activity and monitor administrative changes. You can receive events through a webhook, retrieve stored events through the Audit API, or use both. The API does not require a webhook and does not change an existing webhook configuration.

Choose how to access audit logs

Method	Delivery	Content
Webhook	HTTP POST to your endpoint	Event details and content, where recorded
Audit API	Requests from your integration	Recorded event metadata and content, with credential redaction

Table 1: Webhook delivery and Audit API retrieval.

For events available through both methods, the API returns the recorded event metadata, including query text, answer text, and file names where present. Query and answer text is limited to the first 500 characters in both methods. The comet_agent_action exception described in this article also applies. The payloads are not completely identical: the API uses different top-level field names and redacts credentials in certain webhook-setting changes. See Data privacy and security for the scope of that redaction. The webhook is the faster delivery path. The API has no guaranteed freshness interval. Do not treat it as a guaranteed complete copy of the webhook stream. Audit Logs do not capture every action. Neither method records seat-tier changes made through SCIM, which synchronizes membership with your identity provider, or through bulk tools. Member additions and removals made through CSV bulk operations are also excluded.

Before you start

Confirm that your organization meets the seat requirement above.
Ask an administrator with organization settings access to enable logging.
To manage API keys, use a role with both View audit logs and Perplexity API access. Built-in administrators have both permissions; custom roles can be granted both.
Confirm that API key creation is enabled for your organization. If it is not enabled, contact your account team to request access.
For webhook delivery, prepare an HTTPS endpoint and an authentication value.

See Enterprise roles and permissions for organization settings and API permissions. Audit API keys are separate from regular Perplexity API keys and Analytics API keys.

Data privacy and security

Both methods can contain personal information and recorded content, not just activity identifiers. Depending on the event, metadata can include query and answer text, file names, target member emails, organization-setting values, and Perplexity Computer task details. For webhook authentication-token changes, the API replaces the recorded old and new token values with [REDACTED]. For webhook URL changes, it removes credentials and the URL path, query, and fragment while retaining the destination origin when possible; cleared values remain identifiable as cleared. These redactions apply to API responses for those webhook settings, not to webhook delivery or stored events. They do not remove other recorded personal information or content from API metadata. Restrict access to collected logs according to your organization’s privacy policies. Keep webhook URLs, authentication values, and API keys confidential, and revoke keys you no longer need. For Enterprise-wide data practices, see Data retention and privacy for Enterprise organizations. The Trust Center provides security and compliance documentation, and the Data Processing Addendum sets out contractual data-processing terms when incorporated into your agreement. The session and file deletion settings in Data Retention for Enterprise do not define Audit API retention. Treat your organization’s retention policy for exported logs separately from Perplexity’s storage of audit events. A retention period for Audit API events is not specified here. Collect events promptly and retain copies according to your organization’s policy; ask your account team to confirm the applicable retention terms.

Enable audit logs

Go to Organization Settings.
Open Data and privacy.
Under Audit Log Settings, turn on Enable Audit Logging.

Figure 1: The Enable Audit Logging control in Audit Log Settings.

For API-only use, leave the webhook fields empty and continue to Query audit logs with the API. For webhook delivery, complete these steps:

Enter your HTTPS endpoint in Webhook URL.

Figure 2: Webhook URL and Authorization Header settings.
Click Save beside Webhook URL.
If your endpoint requires authentication, enter the value in Authorization Header.
Click Save beside Authorization Header.

Unless you specify an authorization scheme, Perplexity sends the value you enter as a Bearer token. See Webhook authentication for the two supported formats. After a supported action, confirm that your receiving endpoint receives a webhook event and returns an HTTP 2xx response.

Query audit logs with the API

Use the read-only Audit API to retrieve stored events for investigations or ingestion into a security information and event management (SIEM) system. You control when your integration requests events; no inbound webhook endpoint is required.

Create an Audit API key

Go to Organization Settings > Enterprise APIs and find the Audit API section.
Click Create key.

Figure 3: Audit API key controls in organization settings.
Enter a Key name, such as SIEM production.

Figure 4: Name an Audit API key before creating it.
Click Create key.
When API key created appears, copy the secret.
Store the secret securely. It is shown only once.

If the section is missing, ask an administrator to check both required permissions. If Create key is unavailable, follow the message on the page: enable audit logging if it is off, or contact your account team if API key creation is not enabled for your organization.

Keys belong to your organization, not their creator. Removing the creator or changing their permissions does not revoke a key. Revoke keys you no longer need; revocation stops requests using that key immediately.

Connect your integration

Use your Audit API key to authenticate your integration. Each key can read only its own organization’s audit events and cannot call model APIs. See Audit API for the endpoint, authentication examples, request parameters, response fields, pagination, rate limits, and errors. Use that developer reference when building or maintaining a collector. A request can use either after_id or before_id, but not both.

Content and event coverage

API metadata uses the event-specific fields stored for API retrieval, which can differ from webhook metadata, including for comet_agent_action as described below. Values can include text, nested objects, names, and email addresses; the fields present depend on the event and what was recorded. Some events have no metadata. The shared metadata does not make the API and webhook envelopes interchangeable, or guarantee that every action is captured. The credential redaction applies only to the API; the text limits and recording gaps apply to both methods. For 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. Each successful API read creates an audit_events_accessed event that is available through the API, not the webhook. Request that event type explicitly when reviewing access; it is excluded from the default API feed.

Data availability

Available history begins when your organization enabled audit logging, with no backfill of earlier activity. Stored history does not extend earlier than July 16, 2026.

Turning audit logging off stops new recording and makes API requests return 404. It does not revoke keys or immediately delete stored events. Unrevoked keys work again when logging is re-enabled; keys can still be revoked while logging is off.

How to verify it worked

Use the request example in Audit API to confirm that your integration receives a successful response. An empty event list can mean no events match the selected window and event type; it does not by itself indicate an authentication failure.

Webhook authentication

You can secure your webhook endpoint with a Bearer token or a complete authorization value. Configure the value your receiving endpoint expects.

Bearer token

Provide a token without a prefix, such as YOUR_WEBHOOK_TOKEN. Perplexity prepends Bearer and sends Authorization: Bearer YOUR_WEBHOOK_TOKEN.

Custom authorization header

Provide a complete authorization value that includes its scheme. For example, Splunk YOUR_HEC_TOKEN is sent as Authorization: Splunk YOUR_HEC_TOKEN.

Webhook delivery

Request format

Perplexity delivers audit logs to your webhook URL as HTTP POST requests. The request body uses application/json.

Authentication header

If you configured an authentication value, Perplexity includes it in the Authorization header. See Webhook authentication for Bearer and custom-scheme formats.

Response handling

Your webhook endpoint should return an HTTP 2xx response to acknowledge receipt within 1 second. Perplexity records delivery errors, including HTTP 4xx and 5xx responses, but does not automatically retry failed or timed-out deliveries. Monitor your receiving endpoint for failures and missing events. To recover a missed delivery, query the API for events in the affected period. Recovery is limited to events that were successfully stored and are still available; the API cannot reconstruct events that were never recorded.

Webhook audit log schema

Webhook events use the fields below. For the API’s different top-level field names, see Audit API; the metadata comparison is covered in Query audit logs with the API.

Field	Type	Required	Description
`uuid`	String	Yes	Event identifier
`timestamp`	String	Yes	RFC 3339 timestamp
`event_type`	String	Yes	Event type
`user_email`	String	Yes	Acting member’s email
`ip_address`	String	Yes	Client address or non-IP marker
`user_agent`	String	Yes	Client user agent
`session_id`	String or null	No	Related-event identifier
`user_id`	String or null	No	User identifier, when recorded
`metadata`	Object or null	No	Event-specific data

Table 2: Webhook payload fields.

A required string field can be empty when a value is not recorded. Do not assume that every ip_address value is an IP address.

Event types

The following tables describe documented webhook event types, not a guarantee that every action is recorded or every type is available through both methods. For events available through both methods, the API returns the recorded metadata subject to the redactions described above. The comet_agent_action exception described in this article also applies.

User activity events

Event type	Description
`login`	Successful sign-in
`query`	Search query submitted
`answer_generated`	Answer returned
`file_upload`	File uploaded to a query or Project
`file_download`	File downloaded from a Project
`file_delete`	File deleted from a query or Project

Table 3: User activity events.

Query events can include metadata.attachments, with file_uuid and file_name for each attached file. Both methods can return these nested fields when recorded.

Thread events

Event type	Description
`thread_forked`	Thread copied
`thread_exported`	Thread exported
`thread_shared`	Thread shared
`thread_deleted`	Thread deleted

Table 4: Thread events.

Membership events

Event type	Description
`member_invited`	Member invited
`member_invite_rescinded`	Pending invitation rescinded
`member_removed`	Member removed
`member_role_changed`	Member’s role changed

Table 5: Membership events.

Organization events

Event type	Description
`organization_settings_update`	Organization setting changed

Table 6: Organization events.

Role and group events

Event type	Description
`role_created`	Custom role created
`role_updated`	Role details or permissions updated
`role_deleted`	Custom role deleted
`role_users_changed`	Users added to or removed from a role
`role_groups_changed`	Groups added to or removed from a role
`group_created`	User group created
`group_deleted`	User group deleted
`group_members_changed`	Group membership changed

Table 7: Role and group events.

For role_users_changed and role_groups_changed, metadata can include an action value of added or removed. Use this field to distinguish the direction of a membership change.

Comet agent events

Event type	Description
`comet_agent_action`	Automated Comet action

Table 8: Comet agent events.

Connector events

Event type	Description
`connector_connected`	Third-party Connector connected
`connector_disconnected`	Third-party Connector disconnected

Table 9: Connector events.

Computer events

Event type	Description
`computer_task_started`	Computer task started
`computer_agent_action`	Automated action during a task
`computer_task_completed`	Task completed successfully
`computer_task_error`	Task failed with an error

Table 10: Computer events.

Webhook payload example

This illustrative JSON payload represents a query event delivered to a generic webhook. It is not an Audit API response.

{
  "uuid": "6ba7b810-9dad-41d1-80b4-00c04fd430c8",
  "timestamp": "2026-10-28T09:05:31+00:00",
  "event_type": "query",
  "user_email": "member@example.com",
  "ip_address": "203.0.113.45",
  "user_agent": "ExampleClient/1.0",
  "session_id": "query_abc123",
  "metadata": {
    "query_str": "What are the best practices for API security?"
  }
}

Platform-specific formatting

Slack webhooks

For a webhook URL beginning with https://hooks.slack.com, Perplexity uses Slack’s Block Kit format. The blocks array contains sections for the event type, member and client details, and event metadata when present. Event type labels use title case with underscores removed. Slack formatting truncates individual metadata values at 500 characters and the metadata section at 2,500 characters, with a truncation notice for long values.

Splunk HTTP Event Collector

When the authorization value starts with Splunk, Perplexity wraps the payload in an event object for Splunk’s HTTP Event Collector (HEC). This illustrative example shows the wrapper:

{
  "event": {
    "uuid": "a1b2c3d4-e5f6-4789-abcd-ef1234567890",
    "timestamp": "2026-10-28T09:05:31+00:00",
    "event_type": "login",
    "user_email": "member@example.com",
    "ip_address": "203.0.113.45",
    "user_agent": "ExampleClient/1.0",
    "session_id": null,
    "metadata": {}
  }
}

Generic webhooks

For other webhook destinations, Perplexity sends the standard JSON payload without a platform-specific wrapper. See Webhook payload example for the format.

Common webhook scenarios

Track research sessions

Use session_id to correlate a query with its answer. These steps use webhook field names; API top-level field names differ even when the event metadata matches.

Find the query event

Read query_str in the event’s metadata. Record its session_id to find related events.

Match the answer event

Find the answer_generated event with the same session_id. When recorded, answer contains up to the first 500 characters of the answer, alongside the model used.

Monitor file access

Use file identifiers to correlate uploads and downloads. Both methods can include recorded file and Project details in event metadata.

Find the file upload

Read the upload event’s file_uuid. Record the identifier for comparison with subsequent events.

Match file downloads

Find download events with the same file_uuid. Use the actor and timestamp fields to see who accessed the file and when.

Audit configuration changes

For organization_settings_update, the setting key identifies what changed. Both methods can include old_value and new_value; the API redacts credentials in the webhook settings described in Data privacy and security. Filter stored webhook data by user_email in your own analysis system to track which administrators made changes. The Audit API does not support a user-email filter.

Best practices

Implement your webhook endpoint

Respond promptly: Acknowledge receipt within 1 second.
Process asynchronously: Queue received events for processing.
Validate payloads: Check structure and content before ingestion.
Secure the endpoint: Use HTTPS and validate the configured authentication value.
Monitor failures: Record receiving-end errors and investigate delivery gaps.

Store and analyze collected logs

Set a retention policy: Keep collected logs for the period your organization requires.
Index relevant fields: Use event type, actor, timestamp, and session fields for analysis.
Correlate activity: Use session_id to connect related events.
Monitor patterns: Investigate unusual access or administrative changes.
Maintain backups: Preserve copies according to your organization’s security and privacy policies.

Troubleshooting

Symptom	Possible cause	Next step
No webhook events	Logging or endpoint configuration may be incomplete	Check that logging is enabled and an HTTPS endpoint is saved
Endpoint returns HTTP `4xx` or `5xx`	The receiving endpoint rejected the request or encountered an error	Inspect receiver logs and the configured authentication value
Events missing after a delivery failure	Failed deliveries are not automatically retried	Monitor receiving-end errors; do not rely on automatic replay
API key section is missing	Required permission is missing	Check both permissions
Create key is unavailable	Audit logging is off	Enable audit logging
Create key is unavailable	Organization’s API key creation is not enabled	Contact your account team
API returns no matching events	Window or event filter excludes events	Check dates and `event_type`
API returns `429`	Keys share the organization rate limit	Honor `Retry-After`

Table 11: Troubleshooting.

Check Audit API for response codes and collection guidance. When you contact support, include the exact error and the steps you already tried. Also include the API request time or the time of the affected webhook event or delivery failure, with its timezone. Omit keys, tokens, authentication values (including full authorization headers), and sensitive event content.

Frequently asked questions

Can I use Audit Logs with fewer than 50 seats?

Yes. An organization with fewer than 50 seats can access Audit Logs if at least one seat is on the Enterprise Max plan. See What is Enterprise Max? for eligibility.

What if I enabled Audit Logs by mistake and see an unexpected charge?

Contact your account team or Help > Contact Support to review the charge and any refund eligibility. See Refunds; disabling Audit Logs is not a promise of a billing reversal.

Need more help?

Reach out to your account team or contact us via Help > Contact Support. Visit the Trust Center for security and compliance documentation.

​Overview

​Choose how to access audit logs

​Before you start

​Data privacy and security

​Enable audit logs

​Query audit logs with the API

​Create an Audit API key

​Connect your integration

​Content and event coverage

​Data availability

​How to verify it worked

​Webhook authentication

​Bearer token

​Custom authorization header

​Webhook delivery

​Request format

​Authentication header

​Response handling

​Webhook audit log schema

​Event types

​User activity events

​Thread events

​Membership events

​Organization events

​Role and group events

​Comet agent events

​Connector events

​Computer events

​Webhook payload example

​Platform-specific formatting

​Slack webhooks

​Splunk HTTP Event Collector

​Generic webhooks

​Common webhook scenarios

​Track research sessions

​Monitor file access

​Audit configuration changes

​Best practices

​Implement your webhook endpoint

​Store and analyze collected logs

​Troubleshooting

​Frequently asked questions

​Can I use Audit Logs with fewer than 50 seats?

​What if I enabled Audit Logs by mistake and see an unexpected charge?

​Related references

​Need more help?

Overview

Choose how to access audit logs

Before you start

Data privacy and security

Enable audit logs

Query audit logs with the API

Create an Audit API key

Connect your integration

Content and event coverage

Data availability

How to verify it worked

Webhook authentication

Bearer token

Custom authorization header

Webhook delivery

Request format

Authentication header

Response handling

Webhook audit log schema

Event types

User activity events

Thread events

Membership events

Organization events

Role and group events

Comet agent events

Connector events

Computer events

Webhook payload example

Platform-specific formatting

Slack webhooks

Splunk HTTP Event Collector

Generic webhooks

Common webhook scenarios

Track research sessions

Monitor file access

Audit configuration changes

Best practices

Implement your webhook endpoint

Store and analyze collected logs

Troubleshooting

Frequently asked questions

Can I use Audit Logs with fewer than 50 seats?

What if I enabled Audit Logs by mistake and see an unexpected charge?

Related references

Need more help?