Document audit log search and export

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"
             ]
           }

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.
+
+<Note>
+  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`.
+</Note>
+
+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.
+
+<CodeGroup>
+```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)
+	}
+}
+```
+</CodeGroup>
+
+## 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=<value from X-Next-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.
+
+<CodeGroup>
+```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"))
+}
+```
+</CodeGroup>
+
+## 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=<value from X-Next-Cursor>" \
+  --dump-header audit-logs-next-chunk.headers \
+  --output audit-logs-next-chunk.jsonl.gz
+```
+
+<Warning>
+  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.
+</Warning>
+
+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.

reference/cli.mdx

@@ -61,6 +61,9 @@ kernel --version
   <Card icon="key" title="API Keys" href="/reference/cli/api-keys">
     Create, list, rename, and delete API keys.
   </Card>
+  <Card icon="clock-rotate-left" title="Audit Logs" href="/reference/cli/audit-logs">
+    Search and download organization audit logs.
+  </Card>
 </Columns>
 
 ## Quick Start