# Audit API

Source: https://userguide.qualytics.io/settings/audit/api/

The activity endpoints power the Platform Audit page in the UI. All of them require the **Admin** user role. The list and insights endpoints accept a shared set of filters so the activity log, summary cards, and chart can stay in sync. The changeset endpoint returns the property changes behind a single `update` record, and the verbs endpoint lists the action verbs available for filtering.

> **Tip**
>
> For complete API documentation, including request and response schemas, visit the [API docs](https://userguide.qualytics.io/api/docs) on your Qualytics deployment.

All endpoints are served from your Qualytics deployment (e.g., `https://your-instance.qualytics.io`). The paths below include the `/api` prefix.

---

## List Activity

Return a paginated list of activity records, optionally filtered by user, action, date range, or timeframe window.

**Endpoint**: `GET /api/activity`

**Permission**: Admin user role

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `users` | `list[int]` | One or more user IDs. When set, only activity attributed to the listed users is returned. |
| `actions` | `list[str]` | One or more action verbs (`create`, `update`, `delete`, and others). Filters to the listed verbs only. |
| `start_date` | `date` | The earliest date to include. Use with `end_date` for an explicit range. |
| `end_date` | `date` | The latest date to include. Use with `start_date` for an explicit range, or with `timeframe` as the anchor. |
| `timeframe` | `string` | One of `week`, `month`, `quarter`, `year`. When set, derives `start_date` from `end_date`. |
| `offset` | `int` | Timezone offset in minutes. Applied to the timeframe window boundaries so the date range honors the caller's local calendar. |
| `include_internal` | `bool` | When `true` (the default), includes activity from internal users. Set to `false` to exclude them. |
| `filters` | `string` (JSON) | Narrows the list by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/settings/audit/api/#filtering-lists). |
| `page` | `int` | Page number, starting at 1. |
| `size` | `int` | Page size. |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/activity?timeframe=week&end_date=2026-06-10&include_internal=false&page=1&size=20" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "items": [
>     {
>       "transaction": {
>         "id": 184221,
>         "issued_at": "2026-06-10T18:42:11Z",
>         "user": {
>           "id": 14,
>           "name": "Yannique Kameka",
>           "user_name": "yannique",
>           "email": "yannique@example.com"
>         },
>         "co_author": null
>       },
>       "masking_audit": null,
>       "issued_at": "2026-06-10T18:42:11Z",
>       "user": {
>         "id": 14,
>         "name": "Yannique Kameka",
>         "user_name": "yannique",
>         "email": "yannique@example.com"
>       },
>       "verb": "update",
>       "object_type": "QualityCheck",
>       "object_id": 9821
>     }
>   ],
>   "total": 134,
>   "page": 1,
>   "size": 20,
>   "pages": 7
> }
> ```

### Response schema

| Field | Type | Description |
| --- | --- | --- |
| `items` | `list[object]` | The page of activity records. |
| `items[].issued_at` | `string` | The action timestamp in UTC. |
| `items[].user` | `object` or `null` | The actor (display name, username, email). `null` when the user account no longer exists. |
| `items[].transaction` | `object` or `null` | The change record behind the action. `null` on `unmask_field_values` records, which carry `masking_audit` instead. |
| `items[].transaction.id` | `integer` | Unique transaction identifier. |
| `items[].transaction.issued_at` | `string` | The action timestamp in UTC. |
| `items[].transaction.user` | `object` or `null` | The actor (display name, username, email). `null` when the user account no longer exists. |
| `items[].transaction.co_author` | `object` or `null` | What performed the action on the user's behalf, when it was not done directly. Its `type` is `promote`, `profile`, or `scan` for an operation (with `operation_id` and `datastore_id`), `agent-q` for AgentQ (with `client_id`, `client_name`, `chat_session_id`, and `chat_message_id`), or `flow` for a Flow (with `flow_id`, `flow_name`, `flow_execution_id`, and `action_type`). |
| `items[].masking_audit` | `object` or `null` | Set only on `unmask_field_values` records. Includes `id`, `issued_at`, `user`, `masked_field_names` (the fields whose values were revealed), `ip_address`, and `endpoint`. |
| `items[].verb` | `string` | The recorded action verb (`create`, `update`, `delete`, `activate`, and so on). Archiving is recorded as `delete`, the same verb as a permanent deletion. |
| `items[].object_type` | `string` | The CamelCase entity type (`QualityCheck`, `Anomaly`, and others). Datastores record their specific type, such as `JdbcDatastore` or `DfsDatastore`. On `unmask_field_values` records it is the lowercase resource the values were revealed on: `container`, `container_scan`, `field_profile`, `anomaly`, `quality_check_dry_run`, `export`, or `materialize`. Export and materialize operations write such a record only when they run with `include_masked` set to `true` and the selected containers have masked fields. |
| `items[].object_id` | `integer` or `null` | The ID of the affected entity, when applicable. |
| `total` | `integer` | Total number of records matching the filters. |
| `page` | `integer` | Current page number. |
| `size` | `integer` | Page size. |
| `pages` | `integer` | Total number of pages. |

> **Info**
>
> For the UI equivalent, see [Filter Activity](https://userguide.qualytics.io/settings/audit/how-tos/filter-activity/).

### Filtering Lists

`GET /api/activity` and `GET /api/activity/insights` accept a `filters` parameter: a JSON object with one entry per filter, saying how that filter's values should match.

```bash
curl -G "https://your-instance.qualytics.io/api/activity" \
  --data-urlencode 'filters={"actions":{"not_in":["delete"]}}' \
  -H "Authorization: Bearer YOUR_TOKEN"
```

This returns all activity except deletions.

| Key | Returns |
| --- | --- |
| `in` | The items that match at least one of the values. |
| `not_in` | The items that match none of the values. |
| `all_of` | The items that match every value, on filters an item can have several of, such as tags. |
| `empty` | The items with no value (`true`) or at least one (`false`), on filters an item can lack. |

- Different filters combine with AND, and so do keys on the same filter.
- `empty` can't be combined with other keys on the same filter.
- A filter sent both as its own parameter and inside `filters` returns a `422`. Put all of that filter's conditions in `filters`.
- `in`, `not_in` and `all_of` each take between 1 and 20 values.
- A filter or key the endpoint doesn't accept returns a `422` that names it. The [API docs](https://userguide.qualytics.io/api/docs) list what each endpoint accepts.

---

## Activity Changeset

Return the property changes recorded for a single `update` activity. This is the endpoint that powers the **Changes** section of the activity side panel.

**Endpoint**: `GET /api/activity/{transaction_id}/changeset`

**Permission**: Admin user role

### Path and query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `transaction_id` | `int` | Path parameter. The transaction identifier of the activity record (`items[].transaction.id` from [List Activity](https://userguide.qualytics.io/settings/audit/api/#list-activity)). |
| `object_type` | `string` | Required. The CamelCase entity type recorded by the activity (`items[].object_type`). |
| `object_id` | `int` | Required. The ID of the affected entity (`items[].object_id`). |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/activity/184221/changeset?object_type=QualityCheck&object_id=9821" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "description": ["Original description", "Updated description"],
>   "properties": [
>     { "value": 3 },
>     { "value": 5 }
>   ]
> }
> ```

### Response schema

The response is an object with one key per changed property. Each value is a two-element array holding the original value first and the updated value second. `null` in the first position means the property had no value before the update. Nested objects are returned whole (original and updated versions side by side), and the raw response can include system-managed values, such as update timestamps, that the UI's **Changes** section hides.

Sensitive values, such as integration credentials, are never exposed. The response shows `**********` only on the side where a credential had a value.

Change details remain available after the entity is deleted. When no change record matches the given combination of transaction, entity type, and entity ID, the endpoint returns `404 Not Found`.

> **Info**
>
> For the UI equivalent, see [How It Works](https://userguide.qualytics.io/settings/audit/deep-dive/how-it-works/#update-change-details).

---

## Activity Insights

Return aggregated activity statistics for the timeframe window. This is the endpoint that powers the summary cards and the activity chart.

**Endpoint**: `GET /api/activity/insights`

**Permission**: Admin user role

### Query parameters

| Parameter | Type | Description |
| --- | --- | --- |
| `report_date` | `date` | The end of the timeframe window. Defaults to today when omitted. |
| `timeframe` | `string` | One of `week`, `month`, `quarter`, `year`. Defaults to `month`. |
| `offset` | `int` | Timezone offset in minutes. Applied before date extraction so daily bucketing in `actions_per_day` groups by the caller's local calendar date. |
| `include_internal` | `bool` | When `true` (the default), includes internal users in `total_actions`, `top_entity_type`, and `actions_per_day`. `top_actor` and `unique_actors` always exclude internal users. |
| `filters` | `string` (JSON) | Narrows the activity included in the statistics by one or more filters, written as a JSON object. See [Filtering Lists](https://userguide.qualytics.io/settings/audit/api/#filtering-lists). |
| `users` | `list[int]` | Limit the aggregation to one or more user IDs. |
| `actions` | `list[str]` | Limit the aggregation to one or more action verbs (`create`, `update`, `delete`, and so on). |

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/activity/insights?timeframe=week&report_date=2026-06-10&include_internal=true" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> {
>   "unique_actors": 7,
>   "total_actions": 134,
>   "top_actor": {
>     "id": 14,
>     "name": "Yannique Kameka",
>     "user_name": "yannique",
>     "email": "yannique@example.com",
>     "action_count": 48
>   },
>   "top_entity_type": {
>     "object_type": "Anomaly",
>     "count": 62
>   },
>   "actions_per_day": [
>     { "date": "2026-06-04", "user_count": 18, "system_count": 4 },
>     { "date": "2026-06-05", "user_count": 11, "system_count": 6 },
>     { "date": "2026-06-06", "user_count": 0,  "system_count": 0 },
>     { "date": "2026-06-07", "user_count": 0,  "system_count": 0 },
>     { "date": "2026-06-08", "user_count": 22, "system_count": 7 },
>     { "date": "2026-06-09", "user_count": 25, "system_count": 8 },
>     { "date": "2026-06-10", "user_count": 28, "system_count": 5 }
>   ]
> }
> ```

### Response schema

| Field | Type | Description |
| --- | --- | --- |
| `unique_actors` | `integer` | Number of distinct users, including Service Users, with at least one action in the window. Always excludes internal users. |
| `total_actions` | `integer` | Total number of actions in the window. Respects `include_internal`. |
| `top_actor` | `object` or `null` | The user with the highest action count in the window, never an internal user. Includes `id`, `name`, `user_name`, `email`, and `action_count`. |
| `top_entity_type` | `object` or `null` | The entity type with the highest action count. Includes `object_type` (CamelCase) and `count`. |
| `actions_per_day` | `list[object]` | One entry per day in the window, with `date`, `user_count`, and `system_count`. The page aggregates these into wider buckets (week, month, quarter) when needed. |

> **Info**
>
> For the UI equivalent, see [Summary Section](https://userguide.qualytics.io/settings/audit/how-tos/summary-section/).

---

## Activity Verbs

Return the distinct action verbs present in the activity log, sorted alphabetically. This is the endpoint that powers the **Actions** filter on the page, and it is the quickest way to discover the values you can pass to the `actions` parameter of [List Activity](https://userguide.qualytics.io/settings/audit/api/#list-activity) and [Activity Insights](https://userguide.qualytics.io/settings/audit/api/#activity-insights).

**Endpoint**: `GET /api/activity/verbs`

**Permission**: Admin user role

The endpoint takes no parameters.

> **Example: Example request and response**
>
> **Request**:
>
> ```bash
> curl -X GET "https://your-instance.qualytics.io/api/activity/verbs" \
>   -H "Authorization: Bearer YOUR_TOKEN"
> ```
>
> **Response**:
>
> ```json
> ["create", "delete", "unmask_field_values", "update"]
> ```

> **Info**
>
> For the UI equivalent, see [Filter Activity](https://userguide.qualytics.io/settings/audit/how-tos/filter-activity/).

---

## Error Responses

| Status Code | Description |
| --- | --- |
| `401 Unauthorized` | Missing or invalid API token. |
| `403 Forbidden` | User does not have the **Admin** role. |
| `404 Not Found` | Activity Changeset only: no change record matches the given transaction, entity type, and entity ID. |
| `422 Unprocessable Entity` | Invalid `timeframe`, `offset`, or date value. On the changeset endpoint, also a missing `object_type` or `object_id`, or a non-integer `transaction_id` or `object_id`. |

> **Example: Error response examples**
>
> **403 Forbidden**:
>
> ```json
> { "detail": "Not enough permissions" }
> ```
>
> **422 Unprocessable Entity** (invalid timeframe):
>
> ```json
> {
>   "detail": [
>     {
>       "loc": ["query", "timeframe"],
>       "msg": "value is not a valid enumeration member; permitted: 'week', 'month', 'quarter', 'year'",
>       "type": "type_error.enum"
>     }
>   ]
> }
> ```

---

## Permission Summary

| Operation | Minimum Permission |
| --- | --- |
| List activity | Admin user role |
| Get activity changeset | Admin user role |
| Get activity insights | Admin user role |
| List activity verbs | Admin user role |

*Last updated: November 5, 2026.*
