Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,80 @@ To create a Logpush job:
4. In the datasets section, select the [Audit Logs v2 dataset](/logs/logpush/logpush-job/datasets/account/audit_logs_v2/). Audit Logs v2 is an account-based dataset.
5. Once you are done configuring your logpush job, select **Submit**.

## Resource History

Resource History shows what changed on every configuration modification captured in Audit Logs. For any audit log entry, you can see the sequence of previous changes to the same resource and view a side-by-side diff of what was modified.

Resource History is available in the Cloudflare dashboard and via the Audit Logs API. It uses the audit log entries you already have. There is no additional configuration, no backend recapture, and no changes to how audit logs are generated.

### What Resource History gives you

- **Change history for any resource.** Given any audit log entry, retrieve every other audit log entry for the same resource, ordered chronologically.
- **Field-level before and after.** Compare any two entries in a resource's history to see exactly which fields changed.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please see the other comment. User cannot select two entries freely. Once they pick the audit log entry, all they can change is the past entry to compare with.


### Using Resource History in the dashboard

1. Go to **Manage Account** > **Audit Logs**.
2. Open any audit log entry.
3. Select **Change History** to see the full history for the resource that entry describes.
4. In the history view, select any two entries to see a side-by-side diff of the fields that changed between them.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

User can select a single entry to compare with the selected log. In other words, the user can change the previous log entry to compare with.


When Resource History cannot identify the underlying resource (for example, for certain system-initiated events), the dashboard shows an empty state indicating that change history is not available for that entry.

For a small subset of events, the dashboard may show approximate results (changes to other resources of the same product and type). When this happens, the view displays a warning banner.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

UI doesn't show a warning banner for this. This is used more for internal investigation, so maybe we shouldn't even mention. I suggest we remove this line.


### Using Resource History via the API

You can retrieve the change history for any audit log entry using the History endpoint. Given the `id` of a source audit log entry, the endpoint derives identifying filters from that entry and returns matching audit log entries within a date window you specify.

For account-scoped audit logs, use:

```bash
GET https://api.cloudflare.com/client/v4/accounts/{account_id}/logs/audit/{id}/history
```

For organization-scoped audit logs, use:

```bash
GET https://api.cloudflare.com/client/v4/organizations/{organization_id}/logs/audit/{id}/history
```

The `{id}` path parameter is the `id` of the source audit log entry whose resource history you want to retrieve.

:::note[Required API token permissions]
At least one of the following [token permissions](/fundamentals/api/reference/permissions/) is required:

- `Account Settings Read`
- `Account Settings Write`
:::

The endpoint requires three query parameters:

- `action_time` (required): RFC3339 timestamp of the source audit log entry's action time. Provide the `action.time` value from the audit log identified by `{id}`. This narrows the source-entry lookup window.
- `since` (required): Limits returned results to entries newer than this date. Accepts a date string (`2024-10-30`, interpreted as UTC) or an RFC3339 timestamp.
- `before` (required): Limits returned results to entries older than this date. Same format as `since`.

Optional query parameters:

- `direction`: `desc` (default) or `asc`.
- `limit`: Number of entries to return per page. Default `100`.
- `cursor`: Pagination cursor from a previous response's `result_info.cursor`.

<APIRequest
method="GET"
path="/accounts/{account_id}/logs/audit/{id}/history"
/>

Each entry in `result` has the same shape as an entry returned by the Audit Logs list endpoint. Results are paginated using the `cursor` value in `result_info`.

The `result_info.history_status` field indicates the quality of resource identification used to build the history:

- `exact`: The source entry contained a resource URI, so the history was built from an exact resource match.
- `approximate`: The source entry did not contain a resource URI, so the history was built from an approximate match (other resources of the same product and type). The dashboard surfaces this state with a warning banner.
- `unavailable`: The source entry did not contain enough information to identify the resource. `result` is empty. This can happen for certain system-initiated events.

Resource History reflects the audit log entries currently retained by Audit Logs v2 (refer to [Retention](#retention)). Entries older than the retention window are not returned. Resource History is a query-time capability and is not exposed as additional fields in the `audit_logs_v2` Logpush dataset.

## Audit Log structure

Cloudflare's audit logs offer a detailed view of activity across your environment by capturing both the source of actions and the context in which they occur. These logs are categorized by who initiated the action (user or system) and whether the activity occurred within a specific account or spanned multiple accounts under the same user profile. This structure enables flexible filtering, investigation, and compliance monitoring.
Expand Down
2 changes: 1 addition & 1 deletion src/util/api.ts
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
import SwaggerParser from "@apidevtools/swagger-parser";
import type { OpenAPI } from "openapi-types";

const COMMIT = "082fe875c1438a5874233eef548ff16f8331982b";
const COMMIT = "25d6032915197001c478b9df6f64994d8d6d79cd";
let schema: OpenAPI.Document | undefined;

export const getSchema = async () => {
Expand Down