# How to read your Runtime audit log

Owners and admins can open Audit log in the account. They can also call
`GET /v1/audit` with a key that an owner or admin made, and filter the results
by `action`.

**On Runtime, the audit log comes with every account at no charge. Entries are
kept for at least 400 days.** Nobody can edit or delete an entry before then.
Each entry records the action, its actor, the time, the client's IP address,
the request ID, and whether the request came through the website, the API or
MCP. This is the state as of 26 October 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 cannot 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 use 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

Read every credit event, 200 entries per page:

```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. The tool
takes the same filters.

## Options

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

You can filter on these groups:

| Group         | What it covers                                                                      |
| ------------- | ----------------------------------------------------------------------------------- |
| `member.`     | Joined, added, removed, left, or 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 or deleted. The log never stores values |
| `preview.`    | Preview ports made public or private                                                |
| `resource.`   | Creations and deletions, and sandboxes paused, woken, restarted or stopped          |
| `account.`    | The account created, renamed, suspended or restored                                 |
| `sso.`        | Connections added, changed or removed; domains verified; SSO required               |
| `scim.`       | SCIM tokens, and changes to people and group roles made by your directory           |

## Who did it

The actor on an entry is a person, a key, your directory, or Runtime itself.
Runtime is the actor for events such as a card payment settling. Each key acts
as its own agent. When three CI jobs and a coding agent share an account, the
log shows which key changed a network rule or revoked another key.

## Questions it answers

- **Who revoked the CI key?** Filter `key.` and find 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, not the value.
- **Which address approved a new agent connection?** Filter `connection.`. Each
  entry includes the client IP.
- **What did our directory change overnight?** Filter `scim.`.
- **Who paused that sandbox?** Filter `resource.paused`. An idle pause names
  Runtime and shows that the sandbox was idle.

## Mistakes and how Runtime handles them

- **Looking for what a sandbox did on its own.** Its pauses, wakes, restarts
  and stops are in the audit log under `resource.`, with the actor who requested
  them. Its boots, failures and moves are in its own history. Use `runtime events`
  or the [metrics and events](/docs/observability) API.
- **Reading with a developer's key.** Runtime returns `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. A read-only key is the safer choice for
  a dashboard or an export job.
- **Expecting a `{data, nextCursor}` page.** The audit log returns `events` and
  `next`. Pass `next` back as `before`.

A read-only key made by an admin is the right credential for sending the log to
a SIEM on a schedule. It can read every entry and cannot change anything.

## 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 appear 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 26 October 2026.