# Read the audit log

URL: https://heaven.dev/docs/reference/organizations/audit-view
Updated: 2026-11-21

Read the account's record of changes. Billing owners, admins and members granted `audit view` can read the organization's record. Other members can read their own actions and changes to Computers they own.

`GET /v1/organization/?view=audit`

## Parameters

- `query` (string): Search text, such as a resource name, address, action or actor.
- `actor` (string): Actor to filter by. Give a person's email address or ID, an API key ID, or heaven for changes made by Heaven.
- `action` (string): Action or group filter, such as computer.website.update or computers.
- `since` (string): Start of the history window, as an RFC 3339 timestamp or a duration ago such as 24h. Defaults to 7d. The window can go back up to a year.
- `before` (string): Pagination cursor from the previous response. Returns older entries.
- `limit` (string): Maximum changes per page. Defaults to 50 and accepts up to 500. CSV defaults to 5000 and accepts up to 5000.
- `format` (string): Output format. Give csv for a spreadsheet-compatible file. Omit for the standard response.
- `organization` (string): Organization name or ID. A credential, named resource or sole membership can select the organization for you.

## Returns

- `data` (object, always present): Account audit records matching the request, newest first. Your role determines which records are visible.
  - `account_id` (string, always present): Account whose audit log was read.
  - `csv` (string): This page rendered as CSV when CSV format was requested. May be omitted.
  - `events` (object[] | null, always present): Audit events in this page.
    - `items` (object): A recorded account action.
      - `action` (string, always present): Machine-readable event name.
      - `actor` (object, always present): Person, key or Heaven action responsible.
        - `api_key_id` (string): API key used for the action. May be omitted.
        - `credential` (string): How the person authenticated, such as a browser, SSH key or program sign-in. May be omitted.
        - `email` (string): Person's email. May be omitted.
        - `kind` (string, always present): Actor category: `person`, `api_key` or `heaven`.
        - `label` (string): Key label or MCP client name identifying the credential. May be omitted.
        - `name` (string): Person's display name. May be omitted.
        - `picture` (string): Person's profile picture URL. May be omitted.
        - `user_id` (string): Acting person's ID, including the owner of an API key. May be omitted.
      - `address` (string): Recorded client network address. May be omitted.
      - `at` (string (date-time), always present): When the action was recorded.
      - `changes` (object[]): Saved values before and after the action. May be omitted.
        - `items` (object): One value changed by an audited action.
          - `after` (string, always present): Its resulting value rendered as text.
          - `before` (string, always present): Its previous value rendered as text.
          - `field` (string, always present): Setting that changed.
      - `client` (string): Recorded client identification. May be omitted.
      - `command` (string): Command associated with the action, when applicable. May be omitted.
      - `computer` (object): Affected Computer, named as it was at the time. May be omitted.
        - `id` (string, always present): Object's stable ID.
        - `name` (string, always present): Its name at the time of the event.
      - `group` (string, always present): Event category used by audit filters.
      - `id` (string, always present): Event ID.
      - `parts` (object[] | null, always present): Summary segments marking resource and person names.
        - `items` (object): A display segment of an audit event's summary.
          - `name` (boolean): Whether this segment names a resource or person. May be omitted.
          - `text` (string, always present): Segment's text.
      - `pool` (object): Affected pool, named as it was at the time. May be omitted.
        - `id` (string, always present): Object's stable ID.
        - `name` (string, always present): Its name at the time of the event.
      - `request_id` (string): Request ID for this action. May be omitted.
      - `source` (string, always present): Interface through which the action arrived.
      - `subject` (string): Another object concerned by the action. May be omitted.
      - `summary` (string, always present): A sentence describing the action.
  - `next` (string): Cursor for `before` to fetch the next older page. Absent on the last page. May be omitted.
  - `scope` (string): `yours` limits the read to changes you made and changes to Computers you own. May be omitted.
  - `since` (string (date-time), always present): Start of the selected time range.

## Errors

Each code is explained in full at https://heaven.dev/docs/reference/errors.

| Code | Status | What happened |
|---|---:|---|
| `invalid` | 400 | An input is missing or invalid. |
| `unauthenticated` | 401 | The credential is missing, invalid, expired or revoked. |
| `denied` | 403 | The caller lacks permission for this action. |
| `not_found` | 404 | The resource is absent or inaccessible to this caller. |
| `conflict` | 409 | The request conflicts with the current resource state or an earlier request. |
| `over_capacity` | 409 | The request exceeds a resource or credential allowance. |
| `access_list_full` | 409 | The change would exceed the access-list allowance. |
| `rate_limited` | 429 | The caller's request rate exceeds its limit. |
| `busy` | 429 | Too much work is in progress to accept this request. |
| `unknown` | 503 | The outcome is unconfirmed; a change may have happened. |
| `unavailable` | 503 | The service or requested feature is unavailable. |

## Notes

- API key permission: `audit view`.

## Examples

```sh tab="heaven CLI"
heaven audit view
  [--query QUERY]
  [--actor ACTOR]
  [--action ACTION]
  [--since SINCE]
  [--before BEFORE]
  [--limit N]
  [--format FORMAT]
  [--organization ORGANIZATION]
```

```sh tab="SSH"
ssh cli@heaven.dev audit view
  [--query QUERY]
  [--actor ACTOR]
  [--action ACTION]
  [--since SINCE]
  [--before BEFORE]
  [--limit N]
  [--format FORMAT]
  [--organization ORGANIZATION]
```

```sh tab="cURL"
curl "https://heaven.dev/v1/organization/?view=audit&action=sharing&since=7d" \
  -H "Authorization: Bearer $HEAVEN_API_KEY"
```

```json tab="MCP"
{ "tool": "audit_view",
  "arguments": { "action": "sharing", "since": "7d" } }
```

Response:

```json title="Response excerpt"
{
  "version": 1,
  "data": {
    "account_id": "3b620bbe-ae90-42ed-ab6a-f4cb476fbb58",
    "events": [],
    "since": "2026-11-09T12:00:00Z"
  }
}
```
