---
title: "Search audit events"
method: GET
path: "/api/audit-events/search"
tags: ["Audit Events"]
---

# Search audit events

`GET /api/audit-events/search`

By default, the most recent 100 results will be returned.
            
**Adding filters to the request**
            
For each filter to add, use the following format:
            
    parameterName=value
            
Use & to separate multiple filter values:
            
    parameter1Name=parameter1Value&parameter2Name=parameter2Value
            
**Valid filter parameters**
            
You can filter the included events based on the following parameters:
            
<i>event_category</i> - The general category of event.
For example, to filter the results to only include events related to permission sets:
            
    event_category=PermissionSet
            
You can provide multiple event category values.
For example, to filter the results to include events related to both assigned permissions and permission sets:
            
    event_category=PermissionSet&event_category=AssignedPermissions
            
<i>event_type</i> - The specific type of event.
To get the available event types, refer to Solar.Core.Enums.AuditEvents.AuditEventType.
For example, to filter the results to only include when a permission set was created:
            
    event_type=PermissionSetCreated
            
You can provide multiple event type values.
For example, to filter the results to include both when a permission set was created and when a permission set was updated:
            
    event_type=PermissionSetCreated&event_type=PermissionSetUpdated
            
<i>outcome</i> - Whether the event was successful (<i>Success</i>) or failed (<i>Fail</i>).
For example, to filter the results to only include successful events:
            
    outcome=Success
            
<i>created_before</i> - Used to only include events that occurred before the specified timestamp.
            
The timestamp uses the ISO 8601 format (<i>yyyy-MM-dd'T'HH:mm:ssZ</i>).
For example, to filter the results to only include events that occurred before 6:30 PM UTC on August 1, 2023:
            
    created_before=2023-08-01T18:30:00Z
            
<i>created_after</i> - Used to only include events that occurred after the specified timestamp.
            
The timestamp uses the ISO 8601 format (<i>yyyy-MM-dd'T'HH:mm:ssZ</i>).
For example, to filter the results to only include events that occurred after 10:00 AM UTC on July 27, 2023:
            
    created_after=2023-07-27T10:00:00Z
            
<i>include_unidentified_events</i> - For self-hosted instances, whether to include events that do not have an identified user.
By default, is false. These events might be server-generated or might be related to an unauthenticated action.
To include events that do not have an identified user:
            
    include_unidentified_events=true
            
**Sample requests:**
            
First 100 results by most recent:
            
    GET /api/audit-events/search
            
Returns the first 20 results for permission set events that were successful:
            
    GET /api/audit-events/search?limit=20&event_category=PermissionSet&outcome=Success
### Required Permissions

- **Global:** Manage Users And Groups, View All Datasets

## Query parameters

- `offset` integer
- `limit` integer
- `event_category` AuditEventCategory[]
- `event_type` AuditEventType[]
- `outcome` string
- `created_before` string, date-time
- `created_after` string, date-time
- `include_unidentified_events` boolean

## Response `200`

Returns paginated audit events

- AuditEventModelPaginationResponseModel — Paginated response wrapper containing a page of results along with pagination metadata.
  - `offset` integer — The offset from the first item in the results. For example, 20 indicates that this batch of results starts with the 21st result.
  - `limit` integer — The number of items the request limited the search to. The number of returned items can be less than the limit if not enough items exist or match the filter criteria.
  - `pageNumber` integer — The number for this page of the results, starting at 1.
  - `totalPages` integer — The total number of pages in the results.
  - `totalRecords` integer — The total number of records in the results.
  - `absoluteTotalRecords` integer — The absolute total number of records available (unfiltered). This represents the total count without any search or filter applied.
  - `hasPreviousPage` boolean — Whether there is a previous page of results.
  - `hasNextPage` boolean — Whether there is a next page of results.
  - `records` AuditEventModel[], required — An array of returned records.
    - `id` string — The unique identifier of the audit event.
    - `timestamp` Instant — A point in time represented as an ISO 8601 timestamp string.
    - `eventCategory` 'PermissionSet' | 'AssignedPermissions' | 'UserAuthentication' | 'UserAccountManagement' | 'Api' | 'CustomEntityTypes' | 'Marketplace' | 'OAuth' | 'Dataset' | 'AgentConnection' — <p>Possible values:</p> <ul> <li><b>PermissionSet</b>: Contains events for management of permission sets in the application</li> <li><b>AssignedPermissions</b>: Contains events for permissions that are granted to users or groups for all datasets.</li> <li><b>UserAuthentication</b>: Contains events for user authentication</li> <li><b>UserAccountManagement</b>: Contains events for user account management</li> <li><b>Api</b>: Contains events for API authentication and authorization</li> <li><b>CustomEntityTypes</b>: Contains events for custom entity types</li> <li><b>Marketplace</b>: Contains events for material changes to an organization driven by the GCP Marketplace lifecycle (entitlement attach, plan change, cancellation).</li> <li><b>OAuth</b>: Contains events for material trust decisions in the A2A OAuth flow — currently just consent grants (the user approving a third-party client's persistent access).</li> <li><b>Dataset</b>: Contains events for actions taken on a dataset and its files: file uploads, downloads, deletions, and changes to dataset configuration. Scoped to a single dataset via the AuditEvent.DatasetId column.</li> <li><b>AgentConnection</b>: Contains events for per-user connections from the A2A agent to external file stores (Google Drive; future S3/Azure Blob/SharePoint) and file operations performed through them.</li> </ul>
    - `eventType` 'UserCreated' | 'UserRemoved' | 'UserLogin' | 'ApiAuthentication' | 'ApiAuthorization' | 'PermissionSetCreated' | 'PermissionSetUpdated' | 'PermissionSetDeleted' | 'GlobalPermissionSetAssigned' | 'GlobalPermissionSetRevoked' | 'DatasetPermissionSetAssigned' | 'DatasetPermissionSetRevoked' | 'ModelBasedEntityExported' | 'ModelBasedEntityImported' | 'MarketplaceEntitlementAttached' | 'MarketplaceEntitlementPlanChanged' | 'MarketplaceEntitlementCancelled' | 'OAuthConsentGranted' | 'DatasetFileUploaded' | 'DatasetFileDownloaded' | 'DatasetFilesDownloadedBulk' | 'DatasetFileDeleted' | 'DatasetCreated' | 'DatasetDeleted' | 'DatasetConfigurationChanged' | 'DatasetSettingsImported' | 'DatasetTagsUpdated' | 'DatasetVersionRestored' | 'DatasetPdfRedactionAdded' | 'DatasetPdfRedactionRemoved' | 'DatasetCustomEntityActivated' | 'DatasetCustomEntityDeactivated' | 'ModelBasedEntityRenamed' | 'UserPasswordResetLinkGenerated' | 'MarketplaceAccessRevocationRecovered' | 'DatasetFormMappingSuppressionChanged' | 'RegexEntityExported' | 'RegexEntityImported' | 'CustomEntityImportFailed' | 'AgentConnectionAuthorized' | 'AgentConnectionDisconnected' | 'AgentConnectionRevokedExternally' — The specific type of audit event, such as user creation, login, or permission changes.<p>Possible values:</p> <ul> <li><b>MarketplaceEntitlementAttached</b>: A GCP Marketplace entitlement was first attached to an organization (cold-start).</li> <li><b>MarketplaceEntitlementPlanChanged</b>: A GCP Marketplace entitlement plan change was approved.</li> <li><b>MarketplaceEntitlementCancelled</b>: A GCP Marketplace entitlement was cancelled or deleted (license revoked, refresh tokens swept). Non-deprovisioned state pumps (active↔suspended without permanent change) are NOT audited — they live in the structured log.</li> <li><b>OAuthConsentGranted</b>: The user approved an A2A OAuth consent grant. This is the user's material trust decision; per-issuance token rotations are deliberately not audited.</li> <li><b>DatasetFileUploaded</b>: A file was uploaded to a dataset.</li> <li><b>DatasetFileDownloaded</b>: A dataset file was downloaded (single file, in any output format).</li> <li><b>DatasetFilesDownloadedBulk</b>: Multiple dataset files were downloaded together (download-all / bulk export).</li> <li><b>DatasetFileDeleted</b>: A file was deleted from a dataset.</li> <li><b>DatasetCreated</b>: A dataset was created.</li> <li><b>DatasetDeleted</b>: A dataset was deleted.</li> <li><b>DatasetConfigurationChanged</b>: A dataset's configuration (name, generators, policies, label lists) was changed.</li> <li><b>DatasetSettingsImported</b>: A dataset's settings were imported from another dataset.</li> <li><b>DatasetTagsUpdated</b>: A dataset's tags were updated.</li> <li><b>DatasetVersionRestored</b>: A dataset was restored to a prior configuration version.</li> <li><b>DatasetPdfRedactionAdded</b>: A manual PDF redaction was added to a dataset file.</li> <li><b>DatasetPdfRedactionRemoved</b>: A manual PDF redaction was removed from a dataset file.</li> <li><b>DatasetCustomEntityActivated</b>: A custom or model-based entity type was activated (enabled) for a dataset.</li> <li><b>DatasetCustomEntityDeactivated</b>: A custom or model-based entity type was deactivated (disabled) for a dataset.</li> <li><b>ModelBasedEntityRenamed</b>: A model-based entity was renamed (display name + internal label) via the Entity Type Library Gateway curation surface.</li> <li><b>UserPasswordResetLinkGenerated</b>: An admin generated a self-service password-reset link for another user (self-hosted only).</li> <li><b>MarketplaceAccessRevocationRecovered</b>: A redelivered Pub/Sub event completed revocation (refresh tokens + Marketplace A2A OAuth clients) that a prior delivery had left outstanding after already committing the entitlement's cancelled/deprovisioned state. Distinct from</li> <li><b>DatasetFormMappingSuppressionChanged</b>: A form mapping ("form label mapping") match was suppressed or un-suppressed for a single dataset file, at either grain (whole mapped field, or one occurrence of it). The metadata carries the canonical key, the grain, and the direction.</li> <li><b>RegexEntityExported</b>: A regex-based entity was exported.</li> <li><b>RegexEntityImported</b>: A regex-based entity was imported.</li> <li><b>CustomEntityImportFailed</b>: An entity import failed before its kind could be determined.</li> <li><b>AgentConnectionAuthorized</b>: The user completed provider consent for an agent connection (e.g. Google Drive) and the connection was stored.</li> <li><b>AgentConnectionDisconnected</b>: An agent connection was disconnected. Metadata distinguishes the user disconnecting their own connection from an org admin disconnecting it.</li> <li><b>AgentConnectionRevokedExternally</b>: An agent connection's revocation was detected externally (e.g. `invalid_grant` on a refresh attempt, or a provider admin policy blocking access). Emitted once at detection, not per failed call.</li> </ul>
    - `outcome` 'Fail' | 'Success' — The status of the audit event. Some event types may only log Success or Fail events.
    - `user` string — The user who performed or triggered the event.
    - `message` string — A human-readable description of the event.
    - `requestSource` 'Unknown' | 'Ui' | 'ApiKey' | 'PythonSdk' | 'McpServer' | 'A2aOAuth' | 'OnBehalfOfUser' | 'Fabric' | 'ServerInitiated' — Identifies how the actor communicated with Tonic when an audit event was produced — i.e. the credential/client source behind the request. Answers "was this driven through the UI or programmatically, and if programmatically, via what?".<p>Possible values:</p> <ul> <li><b>Unknown</b>: The request could not be attributed to a known source (e.g. an authenticated request whose credential kind was unclassifiable, or an unauthenticated request).</li> <li><b>Ui</b>: Driven interactively through the browser UI (JWT/cookie bearer authentication).</li> <li><b>ApiKey</b>: A programmatic request authenticated with a user API key (no more specific client identified).</li> <li><b>PythonSdk</b>: A programmatic request from the Textual Python SDK (API key + SDK User-Agent).</li> <li><b>McpServer</b>: A programmatic request from the Textual MCP server (API key + MCP User-Agent).</li> <li><b>A2aOAuth</b>: An agent-to-agent (A2A) OAuth flow.</li> <li><b>OnBehalfOfUser</b>: An on-behalf-of-user delegated token.</li> <li><b>Fabric</b>: A Fabric session.</li> <li><b>ServerInitiated</b>: Produced by the server with no originating HTTP request (background workers, scheduled jobs, EF</li> </ul>
    - `metadata` unknown

## Other responses

- `400` — Invalid filter parameters or unsupported query option

---

[API](https://skmtc.net/tonic/apis/textual-api.md) · [All operations](https://skmtc.net/tonic/apis/textual-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tonic/textual-api/revisions/41da8739a690/schema)