diff --git a/docs.json b/docs.json
index 9b0eef6..4e93dd5 100644
--- a/docs.json
+++ b/docs.json
@@ -116,6 +116,7 @@
]
},
"info/api-keys",
+ "info/audit-logs",
"browsers/file-io",
"browsers/curl",
"browsers/ssh",
@@ -289,6 +290,7 @@
"reference/cli/managed-auth",
"reference/cli/projects",
"reference/cli/api-keys",
+ "reference/cli/audit-logs",
"reference/cli/mcp"
]
}
diff --git a/info/audit-logs.mdx b/info/audit-logs.mdx
new file mode 100644
index 0000000..0f31e5d
--- /dev/null
+++ b/info/audit-logs.mdx
@@ -0,0 +1,301 @@
+---
+title: "Audit Logs"
+description: "Search and export organization API request audit events"
+---
+
+Audit logs record authenticated API requests across your entire organization. Use them to review who called Kernel, which endpoint they called, when the request happened, and how the request completed.
+
+Choose the workflow that matches the amount of data you need:
+
+| Workflow | Best for | Output |
+|----------|----------|--------|
+| Search | Interactive investigation and recent activity | A table, JSON array, or paginated SDK results |
+| Export | Archival, compliance, and offline analysis | JSON Lines (`.jsonl`) or gzip-compressed JSON Lines (`.jsonl.gz`) |
+
+Audit logs are ordered newest first. Time windows use an inclusive `start` and exclusive `end`: `[start, end)`. A search or export can cover up to 30 days. Split longer periods into multiple time windows.
+
+## Filter audit logs
+
+The API and SDKs use the same filters for search and export:
+
+- `auth_strategy` filters by authentication method, such as `api_key`, `dashboard`, or `oauth`.
+- `service` filters by the service that emitted the audit event.
+- `method` includes one HTTP method.
+- `exclude_method` excludes one or more HTTP methods, with up to 10 values.
+- `search` matches path, user ID, email, client IP, and status.
+- `search_user_id` adds up to 100 user IDs to the free-text search.
+
+The CLI exposes the same filters as flags. See the [audit log CLI reference](/reference/cli/audit-logs) for the full list.
+
+## Search with the CLI
+
+Search the previous 24 hours:
+
+```bash
+kernel audit-logs search
+```
+
+Add a time window and filters:
+
+```bash
+kernel audit-logs search \
+ --start 2026-06-01 \
+ --end 2026-06-08 \
+ --search /browsers \
+ --limit 500 \
+ --output json
+```
+
+The CLI accepts RFC 3339 timestamps or `YYYY-MM-DD` dates. Date-only values represent midnight UTC.
+
+
+ The CLI excludes `GET` requests by default to reduce noise. Pass `--include-get` to include them, or `--method GET` to return only `GET` requests. The API and SDKs don't exclude `GET` unless you set `exclude_method`.
+
+
+See the [audit log CLI reference](/reference/cli/audit-logs) for all flags and defaults.
+
+## Search with an SDK
+
+Each API page contains up to 100 events. The SDK pagination helpers request older pages as you iterate.
+
+
+```typescript TypeScript
+import Kernel from '@onkernel/sdk';
+
+const kernel = new Kernel({
+ apiKey: process.env.KERNEL_API_KEY,
+});
+
+for await (const event of kernel.auditLogs.list({
+ start: '2026-06-01T00:00:00Z',
+ end: '2026-06-02T00:00:00Z',
+ limit: 100,
+ method: 'POST',
+})) {
+ console.log(event.timestamp, event.method, event.path, event.status);
+}
+```
+
+```python Python
+import os
+from kernel import Kernel
+
+client = Kernel(api_key=os.environ["KERNEL_API_KEY"])
+
+for event in client.audit_logs.list(
+ start="2026-06-01T00:00:00Z",
+ end="2026-06-02T00:00:00Z",
+ limit=100,
+ method="POST",
+):
+ print(event.timestamp, event.method, event.path, event.status)
+```
+
+```go Go
+package main
+
+import (
+ "context"
+ "fmt"
+ "time"
+
+ "github.com/kernel/kernel-go-sdk"
+)
+
+func main() {
+ ctx := context.Background()
+ client := kernel.NewClient()
+
+ pager := client.AuditLogs.ListAutoPaging(ctx, kernel.AuditLogListParams{
+ Start: time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC),
+ End: time.Date(2026, time.June, 2, 0, 0, 0, 0, time.UTC),
+ Limit: kernel.Int(100),
+ Method: kernel.String("POST"),
+ })
+ for pager.Next() {
+ event := pager.Current()
+ fmt.Println(event.Timestamp, event.Method, event.Path, event.Status)
+ }
+ if err := pager.Err(); err != nil {
+ panic(err)
+ }
+}
+```
+
+
+## Search with HTTP
+
+Search over raw HTTP with a `GET` request. The response carries pagination state in these headers:
+
+- `X-Limit` is the page size applied to the request.
+- `X-Has-More` indicates whether older records remain.
+- `X-Next-Page-Token` contains the opaque token for the next page.
+
+Request the first page:
+
+```bash
+curl --include --get https://api.onkernel.com/audit-logs \
+ --header "Authorization: Bearer $KERNEL_API_KEY" \
+ --data-urlencode "start=2026-06-01T00:00:00Z" \
+ --data-urlencode "end=2026-06-02T00:00:00Z" \
+ --data-urlencode "limit=100"
+```
+
+If `X-Has-More` is `true`, copy the `X-Next-Page-Token` value and pass it unchanged:
+
+```bash
+curl --include --get https://api.onkernel.com/audit-logs \
+ --header "Authorization: Bearer $KERNEL_API_KEY" \
+ --data-urlencode "start=2026-06-01T00:00:00Z" \
+ --data-urlencode "end=2026-06-02T00:00:00Z" \
+ --data-urlencode "limit=100" \
+ --data-urlencode "page_token="
+```
+
+Page tokens are opaque. Don't decode, construct, or modify them.
+
+See the [API reference](https://kernel.sh/docs/api-reference/audit-logs/list-audit-logs) for the complete search contract and response schema.
+
+## Download an export with the CLI
+
+The export workflow is exposed through the `kernel audit-logs download` command and the export-chunk API endpoint. Use the CLI to download every chunk in a time window into one verified gzip-compressed JSONL file:
+
+```bash
+kernel audit-logs download \
+ --start 2026-06-01 \
+ --end 2026-07-01 \
+ --to audit-june.jsonl.gz
+```
+
+The download is all-or-nothing: the CLI verifies every chunk it receives and writes the output file only after the whole export succeeds. Incomplete downloads are removed and don't resume across CLI runs; rerunning the command starts the export again. Use `--force` to replace an existing output file. See the [audit log CLI reference](/reference/cli/audit-logs#download-behavior) for chunk sizes, checksums, and retry behavior.
+
+Like CLI search, CLI download excludes `GET` by default. Search and download accept the same filters.
+
+## Download an export chunk with an SDK
+
+The export API returns one chunk per request. Export paging uses a cursor rather than the page token used by search; both are opaque values you pass back unchanged.
+
+Save the response body exactly as returned, then inspect `X-Has-More`. When it is `true`, pass `X-Next-Cursor` as `cursor` on the next request.
+
+
+```typescript TypeScript
+import { writeFile } from 'node:fs/promises';
+import Kernel from '@onkernel/sdk';
+
+const kernel = new Kernel({
+ apiKey: process.env.KERNEL_API_KEY,
+});
+
+const response = await kernel.auditLogs.exportChunk({
+ start: '2026-06-01T00:00:00Z',
+ end: '2026-06-02T00:00:00Z',
+ format: 'jsonl.gz',
+ exclude_method: ['GET'],
+});
+
+await writeFile(
+ 'audit-logs-chunk.jsonl.gz',
+ Buffer.from(await response.arrayBuffer()),
+);
+
+console.log(response.headers.get('x-has-more'));
+console.log(response.headers.get('x-next-cursor'));
+```
+
+```python Python
+import os
+from kernel import Kernel
+
+client = Kernel(api_key=os.environ["KERNEL_API_KEY"])
+
+response = client.audit_logs.export_chunk(
+ start="2026-06-01T00:00:00Z",
+ end="2026-06-02T00:00:00Z",
+ format="jsonl.gz",
+ exclude_method=["GET"],
+)
+response.write_to_file("audit-logs-chunk.jsonl.gz")
+
+print(response.http_response.headers.get("x-has-more"))
+print(response.http_response.headers.get("x-next-cursor"))
+```
+
+```go Go
+package main
+
+import (
+ "context"
+ "io"
+ "os"
+ "time"
+
+ "github.com/kernel/kernel-go-sdk"
+)
+
+func main() {
+ ctx := context.Background()
+ client := kernel.NewClient()
+
+ response, err := client.AuditLogs.ExportChunk(ctx, kernel.AuditLogExportChunkParams{
+ Start: time.Date(2026, time.June, 1, 0, 0, 0, 0, time.UTC),
+ End: time.Date(2026, time.June, 2, 0, 0, 0, 0, time.UTC),
+ Format: kernel.AuditLogExportChunkParamsFormatJSONLGz,
+ ExcludeMethod: []string{"GET"},
+ })
+ if err != nil {
+ panic(err)
+ }
+ defer response.Body.Close()
+
+ file, err := os.Create("audit-logs-chunk.jsonl.gz")
+ if err != nil {
+ panic(err)
+ }
+ defer file.Close()
+
+ if _, err := io.Copy(file, response.Body); err != nil {
+ panic(err)
+ }
+
+ println(response.Header.Get("X-Has-More"))
+ println(response.Header.Get("X-Next-Cursor"))
+}
+```
+
+
+## Download an export chunk with HTTP
+
+Save the response headers separately from the binary body:
+
+```bash
+curl --fail-with-body --silent --show-error --get \
+ https://api.onkernel.com/audit-logs/export/chunk \
+ --header "Authorization: Bearer $KERNEL_API_KEY" \
+ --data-urlencode "start=2026-06-01T00:00:00Z" \
+ --data-urlencode "end=2026-06-02T00:00:00Z" \
+ --data-urlencode "format=jsonl.gz" \
+ --dump-header audit-logs-chunk.headers \
+ --output audit-logs-chunk.jsonl.gz
+```
+
+When `X-Has-More` is `true`, copy `X-Next-Cursor` and pass it unchanged to download the next chunk:
+
+```bash
+curl --fail-with-body --silent --show-error --get \
+ https://api.onkernel.com/audit-logs/export/chunk \
+ --header "Authorization: Bearer $KERNEL_API_KEY" \
+ --data-urlencode "start=2026-06-01T00:00:00Z" \
+ --data-urlencode "end=2026-06-02T00:00:00Z" \
+ --data-urlencode "format=jsonl.gz" \
+ --data-urlencode "cursor=" \
+ --dump-header audit-logs-next-chunk.headers \
+ --output audit-logs-next-chunk.jsonl.gz
+```
+
+
+ The SDK and HTTP examples above download one chunk. A complete custom exporter must repeat requests until `X-Has-More` is `false`, persist the cursor only after safely writing a chunk, and verify `X-Content-Sha256` against the exact response bytes. Use the CLI when you don't need custom storage or processing.
+
+
+Export chunks contain one JSON object per line. They use the same fields as search results and add `event_id`, which provides a stable tie-breaker when multiple events share a timestamp.
+
+See the [API reference](https://kernel.sh/docs/api-reference/audit-logs/download-an-audit-log-export-chunk) for the complete export contract and response schema.
diff --git a/reference/cli.mdx b/reference/cli.mdx
index 7a47a9d..b0cc1a3 100644
--- a/reference/cli.mdx
+++ b/reference/cli.mdx
@@ -61,6 +61,9 @@ kernel --version
Create, list, rename, and delete API keys.
+
+ Search and download organization audit logs.
+
## Quick Start
diff --git a/reference/cli/audit-logs.mdx b/reference/cli/audit-logs.mdx
new file mode 100644
index 0000000..e8c037d
--- /dev/null
+++ b/reference/cli/audit-logs.mdx
@@ -0,0 +1,93 @@
+---
+title: "Audit Logs"
+---
+
+Search and download [organization audit logs](/info/audit-logs) from the CLI.
+
+## `kernel audit-logs search`
+
+Search audit logs within a time window. Results are ordered newest first.
+
+```bash
+kernel audit-logs search \
+ --start 2026-06-01 \
+ --end 2026-06-08 \
+ --search /browsers \
+ --limit 500 \
+ --output json
+```
+
+If you omit the time flags, the command searches from 24 hours ago through now. The start is inclusive and the end is exclusive. Each time window can cover up to 30 days.
+
+| Flag | Description |
+|------|-------------|
+| `--start