Filtering Audit Events

The Descope Audit Trail supports flexible filtering so you can quickly isolate the events that matter. Filter in the Descope Console, through Management SDKs, or via the Search Audit REST API endpoint.

Filtering in the Descope Console

The Descope Console provides a visual interface for searching and filtering your audit trail without writing any code. Navigate to the Audit page in your project to access these controls.

audit filtering example

Filter by User

Search for audit events tied to a specific user by entering their Login ID (e.g., email address or phone number) or User ID into the search bar.

audit filtering by userID example

Filter by Action

You can use the action to search for items like LoginStarted, LoginSucceed, or general Failed items. See Audit Events for valid values.

audit filtering by failed example

Additional Console Filters

The Console also supports filtering by:

Device: Filter by device category: Desktop, Mobile, Tablet, Bot, or Unknown.
Authentication Method: Filter by method: otp, totp, magiclink, oauth, saml, or password.
Geographic Location: Filter by country code (e.g., US, IL).
Remote Address: Filter by originating IP address.
Tenant: Filter events scoped to a specific tenant.
Level: Filter to Company-level events only. See Company-level Auditing.
Free Text: Full-text search across all audit fields simultaneously.

audit filtering with multiple fields example

Filtering via the Backend SDK

Use the Management SDK when you need programmatic search: custom security dashboards, compliance exports, or alert pipelines.

See Audit with Management SDKs for install steps, the full filter parameter reference, pagination (SearchAll in Go), and code samples in every supported language.

Rate Limiting

Descope enforces a rate limit of 10 requests per minute for audit search operations.

Filtering via the REST API

You can also query audit events directly using the Search Audit REST API endpoint.

The request body accepts the same filter fields documented on the SDK page. Here is an example request:

curl --request POST \
  --url https://api.descope.com/v1/mgmt/audit/search \
  --header 'Authorization: Bearer <management-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "actions": ["LoginSucceed", "LoginFailed"],
    "userIds": ["U2abc123xyz"]
  }'

Understanding Event Types and Actions

Every audit event recorded by Descope has both a type and an action. These two fields have a one-to-one relationship: each action maps to exactly one type. For example, the LoginSucceed action always corresponds to the Information type, while LoginFailed maps to Warning.

Because of this direct mapping, filtering by action in the SDK or API is functionally equivalent to selecting event types in the Console filter dropdown. There is no need to convert between the two. Use whichever is more convenient for your workflow.

For the full list of event types, actions, and their descriptions, see the Audit Events reference.

Was this helpful?

On this page