> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Reference

> API reference for Portal audit log endpoints covering request parameters, filters, pagination, and response field schema.

## API Request Parameters

All query parameters are **optional**.

### Filters

| Parameter        | Type         | Description                                                  | Example                        |
| :--------------- | :----------- | :----------------------------------------------------------- | :----------------------------- |
| `plugin_id`      | string       | Filter by plugin that generated the event                    | `catalog`                      |
| `event_id`       | string       | Filter by event identifier                                   | `entity-fetch`                 |
| `start_time`     | ISO 8601 UTC | Time range start (must end with Z). Defaults to 30 days ago. | `2025-01-01T00:00:00Z`         |
| `end_time`       | ISO 8601 UTC | Time range end (must end with Z). Defaults to current time.  | `2025-01-31T23:59:59Z`         |
| `severity_level` | array        | One or more: `low`, `medium`, `high`, `critical`             | `high` or `high,critical`      |
| `actor_id`       | string       | User or service that performed the action                    | `user:default/john`            |
| `status`         | enum         | `succeeded` or `failed`                                      | `succeeded`                    |
| `actor_type`     | enum         | `user` or `service`                                          | `user`                         |
| `request_method` | string       | HTTP method                                                  | `GET`, `POST`, etc.            |
| `request_url`    | string       | HTTP URL path                                                | `/api/catalog/entities`        |
| `action_type`    | string       | Type of action                                               | `create`                       |
| `query_type`     | string       | Type of query                                                | `query`                        |
| `entity_ref`     | string       | Backstage entity ref                                         | `component:default/my-service` |

### Pagination

| Parameter | Type   | Default | Max  | Description                |
| :-------- | :----- | :------ | :--- | :------------------------- |
| `limit`   | number | 100     | 1000 | Number of results per page |
| `offset`  | number | 0       | -    | Number of results to skip  |

## API Response Fields

The API returns a JSON object with the following structure below. Results are ordered by `event_time` in **descending order** (newest first).

| Field            | Type           | Description                                 |
| :--------------- | :------------- | :------------------------------------------ |
| `id`             | UUID           | Unique identifier for the audit event       |
| `event_time`     | ISO 8601       | When the event occurred                     |
| `recorded_at`    | ISO 8601       | When the event was recorded in the database |
| `plugin_id`      | string         | Plugin that generated the event             |
| `event_id`       | string         | Event identifier                            |
| `severity_level` | enum           | `low`, `medium`, `high`, or `critical`      |
| `status`         | enum           | `succeeded` or `failed`                     |
| `actor_type`     | enum           | `user` or `service`                         |
| `actor_id`       | string         | Entity reference of the actor               |
| `request_method` | string or null | HTTP method if applicable                   |
| `request_url`    | string or null | HTTP URL if applicable                      |
| `action_type`    | string or null | Type of action performed                    |
| `query_type`     | string or null | Type of query                               |
| `entity_ref`     | string or null | Backstage entity reference                  |
| `meta`           | object         | Additional event-specific metadata          |
| `total`          | number         | Total number of matching events             |
| `limit`          | number         | Requested page size                         |
| `offset`         | number         | Current offset                              |

## Audit event directory in Backstage / Portal

The following audit events are emitted by plugins and tracked in Portal's audit log system. Note that Plugin ID, event time, status (succeeded or failed), actor type, actor ID, request method, request URL are all supplied by default.

| Plugin           | Event ID                    | Description                                     | Severity                                                                                                  | Additional Metadata                                                                                                                                                                                                                                                                                                                                                                    |
| :--------------- | :-------------------------- | :---------------------------------------------- | :-------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `catalog`        | `entity-fetch`              | Retrieved entities from the catalog             | `low`                                                                                                     | - **`queryType`**: `all`, `by-query`, `by-uid`, `by-name`, `ancestry`, `by-refs` <br /> - **`meta.query`** (`all`) <br /> - **`meta.uid`** (`by-uid`) <br /> - **`entityRef`** (`by-name`, `ancestry`)                                                                                                                                                                                 |
| `catalog`        | `entity-mutate`             | Modified entities (delete or refresh)           | `medium`                                                                                                  | - **`actionType`**: `delete`, `refresh` <br /> - **`meta.entityRef`** (`refresh`) <br /> - **`meta.uid`** (`delete`)                                                                                                                                                                                                                                                                   |
| `catalog`        | `entity-validate`           | Validated an entity against catalog schema      | `low`                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                        |
| `catalog`        | `entity-facets`             | Retrieved entity facets for filtering/searching | `low`                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                        |
| `catalog`        | `location-fetch`            | Retrieved location information                  | `low`                                                                                                     | - **`queryType`**: `all`, `by-id`, `by-entity` <br /> - **`meta.id`** (`by-id`) <br /> - **`meta.locationRef`** (`by-entity`)                                                                                                                                                                                                                                                          |
| `catalog`        | `location-mutate`           | Created or deleted catalog locations            | `medium` (`low` when `meta.isDryRun` is true)                                                             | - **`actionType`**: `create`, `delete` <br /> - **`meta.location`** (`create`) <br /> - **`meta.isDryRun`** (`create`) <br /> - **`meta.id`** (`delete`)                                                                                                                                                                                                                               |
| `catalog`        | `location-analyze`          | Analyzed a location without registering it      | `low`                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                        |
| `scaffolder`     | `template-parameter-schema` | Retrieved template parameter schemas            | `low`                                                                                                     | `meta.templateRef`                                                                                                                                                                                                                                                                                                                                                                     |
| `scaffolder`     | `action-fetch`              | Retrieved list of installed scaffolder actions  | `low`                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                        |
| `scaffolder`     | `task`                      | Operations related to scaffolder tasks (runs)   | `low` (for `actionType` `get`, `list`, `stream`, `events`, `dry-run`) medium (for all other `actionType`) | - **`actionType`**: `stale-cancel`, `execution`, `action`, `list`, `get`, `cancel`, `retry`, `stream`, `events`, `dry-run` <br /> - **`meta.taskId`** (`stale-cancel`, `execution`, `get`, `cancel`, `retry`, `stream`, `events`) <br /> - **`meta.createdBy`** (`execution`) <br /> - **`meta.taskParameters`** (`execution`) <br /> - **`meta.templateRef`** (`execution`, `create`) |
| `rbac`           | `policy-mutate`             | RBAC policy created, edited, or deleted         | `high` (for `actionType` `publish`) `medium` (for all other `actionType`)                                 | - **`actionType`**: `update`, `delete`, `create`, `publish` <br /> - **`meta.id`** (`update`, `delete`, `create`, `publish`) <br /> - **`meta.includedUpdate`** (`publish`) <br /> - **`meta.description`** (`publish`)                                                                                                                                                                |
| `rbac`           | `permission-check`          | RBAC admin authorization denied                 | `medium`                                                                                                  | - **`actionType`**: `authorize` <br /> - **`decision`**: `DENY`                                                                                                                                                                                                                                                                                                                        |
| `config-manager` | `plugin-mutate`             | Change made to plugin                           | `medium`                                                                                                  | - **`actionType`**: `add`, `remove`, `installed`, `uninstalled` <br /> - **`meta.plugin`** <br /> - **`meta.artifactId`** (`installed`, `uninstalled`) <br /> - **`meta.packages`** (`installed`, `uninstalled`)                                                                                                                                                                       |
| `config-manager` | `module-mutate`             | Change made to module                           | `medium`                                                                                                  | - **`actionType`**: `add`, `remove` <br /> - **`meta.module`**                                                                                                                                                                                                                                                                                                                         |
| `config-manager` | `config-mutate`             | Change made to configuration                    | `medium`                                                                                                  | - **`actionType`**: `save`, `activate`, `patch` <br /> - **`meta.configId`** (`activate`)                                                                                                                                                                                                                                                                                              |
| `config-manager` | `admin-config-mutate`       | Change made to admin configuration              | `medium`                                                                                                  | **`actionType`**: `update`, `publish`                                                                                                                                                                                                                                                                                                                                                  |