# How to read your Runtime audit log

Owners and admins open Audit log in the account, or call `GET /v1/audit` with a key an owner or admin made, filtered by `action`.

**On Runtime the audit log comes with every account at no charge, and entries
are kept for at least 400 days.** Nobody can edit an entry or delete one
before then. Each records the action, who did it, the time, the client's IP
address, the request id and whether it came through the website, the API or
MCP, as of 25 September 2026 ([teams](/docs/teams#audit-log)).

## Read it in the browser

Sign in as an owner or admin and open
[Audit log](https://withruntime.com/account/audit). Developers and billing
members do not see it.

## Read it from a terminal

```bash no-run
npx withruntime audit                          # newest first
npx withruntime audit --action key.            # only key events
npx withruntime audit --action member. --limit 100
npx withruntime audit --before <next>          # the page after that
```

Or with curl:

```bash no-run
curl -sS -H "Authorization: Bearer ${RUNTIME_API_KEY}" \
  "https://api.withruntime.com/v1/audit?action=secret.&limit=200"
```

## Read it from code

Page back through every credit event, 200 at a time:

```ts check
import { Runtime } from "withruntime";

const runtime = new Runtime();
let before: string | undefined;
do {
  const page = await runtime.audit.list({
    action: "credit.",
    limit: 200,
    ...(before ? { before } : {}),
  });
  for (const event of page.events) console.log(event);
  before = page.next ?? undefined;
} while (before);
```

```python check
from withruntime import Runtime

with Runtime() as runtime:
    before = None
    while True:
        page = runtime.audit.list(action="credit.", limit=200, before=before)
        for event in page["events"]:
            print(event)
        before = page["next"]
        if not before:
            break
```

An agent reads the same log with the `runtime_audit_list` MCP tool, which
takes the same filters.

## Options

| Option   | What it does                                                  |
| -------- | ------------------------------------------------------------- |
| `action` | One action, such as `key.created`, or a group ending in a dot |
| `limit`  | Entries per page, 1 to 200; 50 by default                     |
| `before` | The `next` value of the previous page, for older entries      |
| Order    | Always newest first                                           |

The groups you can filter on:

| Group         | What it covers                                                      |
| ------------- | ------------------------------------------------------------------- |
| `member.`     | Joined, added, removed, left, role changed                          |
| `invitation.` | Invitations sent and withdrawn                                      |
| `key.`        | Keys created and revoked                                            |
| `connection.` | CLI connections and key requests approved or denied                 |
| `limit.`      | Daily spending limits set and removed                               |
| `credit.`     | Top-ups, purchases, grants, referral credit, refunds, disputes      |
| `network.`    | Network rules changed                                               |
| `secret.`     | Secrets created, updated, rotated, revealed, deleted (never values) |
| `preview.`    | Preview ports made public or private                                |
| `resource.`   | Volumes, images, snapshots, services and jobs deleted               |
| `account.`    | The account created, renamed, suspended, restored                   |
| `sso.`        | Connections added, changed, removed; domains verified; SSO required |
| `scim.`       | SCIM tokens, and people and group roles your directory changed      |

## Who did it

The actor on an entry is a person, a key, your directory, or Runtime itself
for things like a card payment settling. Each key is its own agent, so when
three CI jobs and a coding agent share an account, the log says which key
changed a network rule or revoked another key.

## Questions it answers

- **Who revoked the CI key?** Filter `key.` and look for the revocation.
- **Who gave a contractor admin?** Filter `member.` for the role change.
- **Was a secret's value ever shown?** Filter `secret.` for a reveal. The log
  records the event, never the value.
- **Which address approved a new agent connection?** Filter `connection.`;
  each entry carries the client IP.
- **What did our directory change overnight?** Filter `scim.`.

## Mistakes and how Runtime handles them

- **Looking for sandbox starts and stops.** They are not in the audit log.
  Each sandbox has its own history: use `runtime events` or the
  [metrics and events](/docs/observability) API.
- **Reading with a developer's key.** Runtime answers `403 forbidden`. The key
  must be made by an owner or admin.
- **Reading with a key limited to selected actions.** Also `403`. Use a key
  with full access, or a read-only key, which is the safer choice for a
  dashboard or an export job.
- **Expecting a `{data, nextCursor}` page.** The audit log answers `events`
  and `next`; pass `next` back as `before`.

A read-only key made by an admin is the right credential for shipping the log
to a SIEM on a schedule: it reads every entry and can change nothing.

## Related

- [How to invite your team](/how-to/invite-your-team) and
  [how to set up single sign-on](/how-to/set-up-single-sign-on), whose
  changes all land here
- [Security](/docs/security#read-only-keys-and-daily-limits) for read-only
  keys
- [HTTPS API reference](/docs/api#account)

Facts on this page were checked on 25 September 2026.