# List the audit log

`GET /apis/cra.diagrid.io/v1beta1/auditlog`

List an organization's audit log: its Activity events and the calls made to its regions' management APIs, as one list ordered by time. Each row says which log it came from in `log`, and leaves empty the fields that log does not record. Region calls are listed, not verified: their rows carry integrity status `INTEGRITY_STATUS_NOT_CHECKED`, and `diagrid audit verify` checks their signatures. Recent rows are read from Loki and older ones from the signed archives.

## Request

### Query parameters

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `startTime` | string (date-time) | No | Inclusive lower bound of the query window (RFC3339). |
| `endTime` | string (date-time) | No | Exclusive upper bound of the query window (RFC3339). |
| `logs` | string[] | No | The logs to read: `AUDIT_LOG_ACTIVITY` for Activity events, `AUDIT_LOG_REGION` for calls to a region's management API. Omit for both. |
| `method` | string[] | No | Filter to rows whose HTTP method matches any of these, case-insensitively. Rows without a method are excluded. |
| `success` | boolean | No | true keeps only successful rows, false only failed ones. An Activity event is judged by its payload's success flag, a region call by its status, which succeeded when below 400. Omit for both; rows with neither are excluded when it is set. |
| `search` | string | No | Free-text substring match over the stored line, case-insensitive. |
| `actor` | string | No | Only rows made by this actor, matched exactly: an Activity event's source id, or a region call's actor email, client id or subject. |
| `serviceName` | string[] | No | Filter to Activity events emitted by any of these services. Region calls never match. |
| `entryType` | string[] | No | Filter to Activity events of any of these types. Region calls never match. |
| `sourceType` | string[] | No | Filter to Activity events whose source type matches any of these. Region calls never match. |
| `correlationId` | string | No | Only Activity events carrying exactly this correlation ID. Region calls never match. |
| `projectId` | string | No | Only region calls made to this project. Activity events never match. |
| `sortOrder` | string | No | Order of the rows by time. Defaults to SORT_ORDER_DESC, newest first. One of: `SORT_ORDER_ASC`, `SORT_ORDER_DESC`. |
| `page` | string | No | Opaque cursor from a prior response's nextPage. |
| `limit` | integer (int32) | No | Maximum number of rows per page. Defaults to 100. A value above 1000 is treated as 1000. Default: `100`. |

## Responses

### 200 — The page of audit log rows.

`application/json`

A page of the audit log plus per-archive integrity summaries.

- `rows` (object[]) — The matching rows, ordered by `time` and then `id`, in the requested order.
  - `log` (string) — The log the row came from. `AUDIT_LOG_ACTIVITY`: the control plane's Activity events. `AUDIT_LOG_REGION`: calls to a region's management API. One of: `AUDIT_LOG_UNSPECIFIED`, `AUDIT_LOG_ACTIVITY`, `AUDIT_LOG_REGION`.
  - `id` (string) — The SHA-256 of the stored line, a stable identifier for the row.
  - `time` (string (date-time)) — What the rows are ordered by: an Activity event's timestamp, or when the region wrote the call's line, after the call was answered.
  - `callTime` (string (date-time)) — When a region call started.
  - `actor` (string) — Who acted. For an Activity event, its source id, shown as the user's email when it can be resolved. For a region call, the actor's email, else its client id, else its subject.
  - `actorType` (string) — An Activity event's source type, or a region call's authentication method (`api_key` or `jwt`).
  - `method` (string) — The HTTP method of the request, when the row records one.
  - `path` (string) — The HTTP path of the request, when the row records one.
  - `status` (integer (int32)) — The HTTP status of the response, when the row records one.
  - `route` (string) — The route pattern a region call matched.
  - `ipAddr` (string) — The caller's IP address, as recorded.
  - `userAgent` (string) — The caller's user agent, as recorded.
  - `resourceType` (string) — The type of the resource an Activity event acted on.
  - `resourceId` (string) — The id of the resource an Activity event acted on.
  - `action` (string) — What an Activity event did to the resource.
  - `serviceName` (string) — The service that recorded an Activity event.
  - `entryType` (string) — An Activity event's type.
  - `correlationId` (string) — An Activity event's correlation ID, which ties together the events of one request.
  - `traceId` (string) — A region call's trace ID.
  - `projectId` (string) — The project a region call was made to.
  - `integrity` (object) — The tamper-check status for a single audit event.
    - `status` (string) — The integrity verdict. `INTEGRITY_STATUS_VERIFIED`: the checksum matched and, for archived events, so did the HMAC signature. `INTEGRITY_STATUS_CHECKSUM_MISMATCH`: the checksum did not match, so the event was corrupted or altered. `INTEGRITY_STATUS_SIGNATURE_MISMATCH`: the checksum matched but the signature did not, which indicates tampering. `INTEGRITY_STATUS_UNVERIFIABLE`: integrity could not be checked. `INTEGRITY_STATUS_NOT_CHECKED`: no check was run, as for a region call in the audit log, whose signature `diagrid audit verify` checks. `INTEGRITY_STATUS_UNSPECIFIED`: no verdict was recorded. One of: `INTEGRITY_STATUS_UNSPECIFIED`, `INTEGRITY_STATUS_VERIFIED`, `INTEGRITY_STATUS_CHECKSUM_MISMATCH`, `INTEGRITY_STATUS_SIGNATURE_MISMATCH`, `INTEGRITY_STATUS_UNVERIFIABLE`, `INTEGRITY_STATUS_NOT_CHECKED`.
    - `source` (string) — The backing store the event was read from. One of: `DATA_SOURCE_UNSPECIFIED`, `DATA_SOURCE_LOKI`, `DATA_SOURCE_ARCHIVE`.
    - `checksum` (string) — The SHA256 checksum (hex) associated with the event or its archive.
    - `keyId` (string) — The HMAC key id used to sign the archive, when signed.
    - `archiveKey` (string) — The S3 object key backing this event when read from an archive.
  - `activity` (object) — A single audit event.
    - `id` (string) — A stable identifier for the event.
    - `correlationId` (string)
    - `serviceName` (string)
    - `timestamp` (string (date-time))
    - `organizationId` (string)
    - `source` (object)
      - `type` (string)
      - `id` (string)
    - `entryType` (string)
    - `entry` (object) — The structured event payload.
    - `integrity` (object) — The tamper-check status for a single audit event.
      - `status` (string) — The integrity verdict. `INTEGRITY_STATUS_VERIFIED`: the checksum matched and, for archived events, so did the HMAC signature. `INTEGRITY_STATUS_CHECKSUM_MISMATCH`: the checksum did not match, so the event was corrupted or altered. `INTEGRITY_STATUS_SIGNATURE_MISMATCH`: the checksum matched but the signature did not, which indicates tampering. `INTEGRITY_STATUS_UNVERIFIABLE`: integrity could not be checked. `INTEGRITY_STATUS_NOT_CHECKED`: no check was run, as for a region call in the audit log, whose signature `diagrid audit verify` checks. `INTEGRITY_STATUS_UNSPECIFIED`: no verdict was recorded. One of: `INTEGRITY_STATUS_UNSPECIFIED`, `INTEGRITY_STATUS_VERIFIED`, `INTEGRITY_STATUS_CHECKSUM_MISMATCH`, `INTEGRITY_STATUS_SIGNATURE_MISMATCH`, `INTEGRITY_STATUS_UNVERIFIABLE`, `INTEGRITY_STATUS_NOT_CHECKED`.
      - `source` (string) — The backing store the event was read from. One of: `DATA_SOURCE_UNSPECIFIED`, `DATA_SOURCE_LOKI`, `DATA_SOURCE_ARCHIVE`.
      - `checksum` (string) — The SHA256 checksum (hex) associated with the event or its archive.
      - `keyId` (string) — The HMAC key id used to sign the archive, when signed.
      - `archiveKey` (string) — The S3 object key backing this event when read from an archive.
  - `regionLine` (string) — A region call's line exactly as stored. Its signature covers these bytes, so it is what `diagrid audit verify` checks.
- `nextPage` (string) — Opaque cursor for the next page; empty when exhausted. A page can hold fewer rows than limit, or none, and still carry one.
- `archives` (object[]) — The integrity of each archive, of either log, read for this page.
  - `archiveKey` (string)
  - `status` (string) — The integrity verdict for the archive, with the same values as the event-level `integrity.status`. One of: `INTEGRITY_STATUS_UNSPECIFIED`, `INTEGRITY_STATUS_VERIFIED`, `INTEGRITY_STATUS_CHECKSUM_MISMATCH`, `INTEGRITY_STATUS_SIGNATURE_MISMATCH`, `INTEGRITY_STATUS_UNVERIFIABLE`.
  - `windowStart` (string (date-time))
  - `windowEnd` (string (date-time))
  - `keyId` (string)

### 400 — The request is not valid, for example the time range or the `page` cursor is malformed.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 401 — Authentication failed: the credentials are missing or not valid, or the `x-diagrid-orgid` header names a different organization than the credentials.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 403 — Your role does not allow listing audit events. This needs an organization-wide admin role.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 404 — This control plane does not serve the audit log yet. List audit events with `listAuditEvents` instead.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 500 — The audit service returned an error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 501 — The audit log is not enabled on this control plane.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### 503 — The audit service is unavailable. Retry later.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.

### default — Unexpected error.

`application/json`

In the case of an error, a standard format error response body will be returned and the HTTP status code will be set to an error status. The response contains an object with a single error object.

- `code` (string) — Required. This is the same as the HTTP status of the response.
- `message` (string) — Required. A short description of the error.
- `status` (object) — Required. A status code that indicates the error type.
- `details` (object) — Additional details about the errors.
  - `@type` (string) — The type of error.
  - `reason` (string) — A reason for the error.
  - `domain` (string) — The domain in which the error occurred.
  - `metadata` (object) — Additional metadata about the error.
