From c4e31b8eb6f3df80ed14cd9e5b4cfa15ec881ee8 Mon Sep 17 00:00:00 2001 From: sahidya Date: Thu, 9 Jul 2026 13:26:00 -0400 Subject: [PATCH 1/2] [Audit Logs] Add Resource History section to Audit Logs v2 page --- .../account/account-security/audit-logs.mdx | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) diff --git a/src/content/docs/fundamentals/account/account-security/audit-logs.mdx b/src/content/docs/fundamentals/account/account-security/audit-logs.mdx index 69eb5fea030..53dbadfe856 100644 --- a/src/content/docs/fundamentals/account/account-security/audit-logs.mdx +++ b/src/content/docs/fundamentals/account/account-security/audit-logs.mdx @@ -125,6 +125,102 @@ 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. + +### 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. + +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. + +### Using Resource History via the API + +You can retrieve the change history for any audit log entry using the History endpoint. The endpoint accepts the ID of a source audit log entry and returns every other audit log entry for the same resource, ordered chronologically. + +For account-scoped audit logs, use: + +```bash +GET https://api.cloudflare.com/client/v4/accounts/{account_id}/logs/audit/{audit_log_id}/history +``` + +For organization-scoped audit logs, use: + +```bash +GET https://api.cloudflare.com/client/v4/organizations/{organization_id}/logs/audit/{audit_log_id}/history +``` + +:::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` + ::: + + + +```json title="Example response" +{ + "result": [ + { + "id": "abc123", + "action": { + "type": "update", + "time": "2026-06-15T14:38:16Z", + "result": "success" + }, + "actor": { + "email": "user@example.com", + "type": "user" + }, + "resource": { + "id": "dns-record-123", + "product": "dns_records", + "type": "record" + }, + "raw": { + "uri": "/zones/xyz/dns_records/dns-record-123", + "method": "PATCH" + } + } + ], + "result_info": { + "cursor": "next-page-cursor", + "history_status": "available" + }, + "success": true, + "errors": [], + "messages": [] +} +``` + +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`. + +To improve performance on large accounts, pass the source entry's `action.time` value as the `action_time` query parameter. This narrows the history query around the source entry and returns faster than an unconstrained query. + +The `result_info.history_status` field indicates whether change history was available: + +- `available`: Change history was returned in `result`. +- `unavailable`: The source audit log entry does not carry enough information to identify the underlying resource, so change history cannot be returned. 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. From 76500d3b90d0f4a5fb4aff232ae4882efcbae516 Mon Sep 17 00:00:00 2001 From: sahidya Date: Tue, 14 Jul 2026 12:30:41 -0400 Subject: [PATCH 2/2] [Audit Logs] Align Resource History API docs with OpenAPI schema - Fix path parameter from {audit_log_id} to {id} to match spec. - Document required query params: action_time, since, before. - Document optional query params: direction, limit, cursor. - Correct history_status values to exact, approximate, unavailable. - Remove hand-written response example; APIRequest renders from schema. - Bump pinned api-schemas commit so History endpoint resolves. --- .../account/account-security/audit-logs.mdx | 66 +++++++------------ src/util/api.ts | 2 +- 2 files changed, 23 insertions(+), 45 deletions(-) diff --git a/src/content/docs/fundamentals/account/account-security/audit-logs.mdx b/src/content/docs/fundamentals/account/account-security/audit-logs.mdx index 53dbadfe856..d2950056987 100644 --- a/src/content/docs/fundamentals/account/account-security/audit-logs.mdx +++ b/src/content/docs/fundamentals/account/account-security/audit-logs.mdx @@ -149,20 +149,22 @@ For a small subset of events, the dashboard may show approximate results (change ### Using Resource History via the API -You can retrieve the change history for any audit log entry using the History endpoint. The endpoint accepts the ID of a source audit log entry and returns every other audit log entry for the same resource, ordered chronologically. +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/{audit_log_id}/history +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/{audit_log_id}/history +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: @@ -170,54 +172,30 @@ At least one of the following [token permissions](/fundamentals/api/reference/pe - `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`. + -```json title="Example response" -{ - "result": [ - { - "id": "abc123", - "action": { - "type": "update", - "time": "2026-06-15T14:38:16Z", - "result": "success" - }, - "actor": { - "email": "user@example.com", - "type": "user" - }, - "resource": { - "id": "dns-record-123", - "product": "dns_records", - "type": "record" - }, - "raw": { - "uri": "/zones/xyz/dns_records/dns-record-123", - "method": "PATCH" - } - } - ], - "result_info": { - "cursor": "next-page-cursor", - "history_status": "available" - }, - "success": true, - "errors": [], - "messages": [] -} -``` - 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`. -To improve performance on large accounts, pass the source entry's `action.time` value as the `action_time` query parameter. This narrows the history query around the source entry and returns faster than an unconstrained query. - -The `result_info.history_status` field indicates whether change history was available: +The `result_info.history_status` field indicates the quality of resource identification used to build the history: -- `available`: Change history was returned in `result`. -- `unavailable`: The source audit log entry does not carry enough information to identify the underlying resource, so change history cannot be returned. This can happen for certain system-initiated events. +- `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. diff --git a/src/util/api.ts b/src/util/api.ts index 46d95e56a8e..aebc3e7a037 100644 --- a/src/util/api.ts +++ b/src/util/api.ts @@ -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 () => {