docs: add data retention and export documentation for AI Bridge (#21055)

mafredri · web-flow · commit f1b271555537 · 2025-12-03T11:39:36.000+02:00
Previously AI Bridge retention was only documented in the auto-generated CLI reference, making it difficult for administrators to discover and understand how to configure data retention for compliance requirements. This adds retention configuration to the AI Bridge setup guide with examples, documents the REST API and CLI export options in the monitoring guide, and cross-references AI Bridge from the central data retention page for discoverability. Closes #21038
diff --git a/docs/admin/setup/data-retention.md b/docs/admin/setup/data-retention.md
@@ -1,8 +1,9 @@
 # Data Retention
 
 Coder supports configurable retention policies that automatically purge old
-Audit Logs, Connection Logs, Workspace Agent Logs, and API keys. These policies
-help manage database growth by removing records older than a specified duration.
+Audit Logs, Connection Logs, Workspace Agent Logs, API keys, and AI Bridge
+records. These policies help manage database growth by removing records older
+than a specified duration.
 
 ## Overview
 
@@ -32,6 +33,12 @@ a YAML configuration file.
 | Connection Logs      | `--connection-logs-retention`      | `CODER_CONNECTION_LOGS_RETENTION`      | `0` (disabled) | How long to retain Connection Logs      |
 | API Keys             | `--api-keys-retention`             | `CODER_API_KEYS_RETENTION`             | `7d`           | How long to retain expired API keys     |
 | Workspace Agent Logs | `--workspace-agent-logs-retention` | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | `7d`           | How long to retain workspace agent logs |
+| AI Bridge            | `--aibridge-retention`             | `CODER_AIBRIDGE_RETENTION`             | `60d`          | How long to retain AI Bridge records    |
+
+> [!NOTE]
+> AI Bridge retention is configured separately from other retention settings.
+> See [AI Bridge Setup](../../ai-coder/ai-bridge/setup.md#data-retention) for
+> detailed configuration options.
 
 ### Duration Format
 
@@ -51,7 +58,8 @@ coder server \
   --audit-logs-retention=365d \
   --connection-logs-retention=90d \
   --api-keys-retention=7d \
-  --workspace-agent-logs-retention=7d
+  --workspace-agent-logs-retention=7d \
+  --aibridge-retention=60d
 ```
 
 ### Environment Variables Example
@@ -61,6 +69,7 @@ export CODER_AUDIT_LOGS_RETENTION=365d
 export CODER_CONNECTION_LOGS_RETENTION=90d
 export CODER_API_KEYS_RETENTION=7d
 export CODER_WORKSPACE_AGENT_LOGS_RETENTION=7d
+export CODER_AIBRIDGE_RETENTION=60d
 ```
 
 ### YAML Configuration Example
@@ -71,6 +80,9 @@ retention:
   connection_logs: 90d
   api_keys: 7d
   workspace_agent_logs: 7d
+
+aibridge:
+  retention: 60d
 ```
 
 ## How Retention Works
@@ -116,6 +128,17 @@ For non-latest builds, logs are deleted if the agent hasn't connected within the
 retention period. Setting `--workspace-agent-logs-retention=7d` deletes logs for
 agents that haven't connected in 7 days (excluding those from the latest build).
 
+### AI Bridge Data Behavior
+
+AI Bridge retention applies to interception records and all related data,
+including token usage, prompts, and tool invocations. The default of 60 days
+provides a reasonable balance between storage costs and the ability to analyze
+usage patterns.
+
+For details on what data is retained, see the
+[AI Bridge Data Retention](../../ai-coder/ai-bridge/setup.md#data-retention)
+documentation.
+
 ## Best Practices
 
 ### Recommended Starting Configuration
@@ -128,6 +151,9 @@ retention:
   connection_logs: 90d
   api_keys: 7d
   workspace_agent_logs: 7d
+
+aibridge:
+  retention: 60d
 ```
 
 ### Compliance Considerations
@@ -171,6 +197,9 @@ retention:
   connection_logs: 0s      # Keep connection logs forever
   api_keys: 0s             # Keep expired API keys forever
   workspace_agent_logs: 0s # Keep workspace agent logs forever
+
+aibridge:
+  retention: 0s            # Keep AI Bridge records forever
 ```
 
 ## Monitoring
@@ -185,3 +214,9 @@ containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
   purge procedures.
 - [Connection Logs](../monitoring/connection-logs.md): Learn about Connection
   Logs and monitoring.
+- [AI Bridge](../../ai-coder/ai-bridge/index.md): Learn about AI Bridge for
+  centralized LLM and MCP proxy management.
+- [AI Bridge Setup](../../ai-coder/ai-bridge/setup.md#data-retention): Configure
+  AI Bridge data retention.
+- [AI Bridge Monitoring](../../ai-coder/ai-bridge/monitoring.md): Monitor AI
+  Bridge usage and metrics.
diff --git a/docs/ai-coder/ai-bridge/index.md b/docs/ai-coder/ai-bridge/index.md
@@ -35,5 +35,5 @@ AI Bridge is best suited for organizations facing these centralized management a
 - [Set up AI Bridge](./setup.md) on your Coder deployment
 - [Configure AI clients](./client-config.md) to use AI Bridge
 - [Configure MCP servers](./mcp.md) for tool access
-- [Monitor usage and metrics](./monitoring.md)
+- [Monitor usage and metrics](./monitoring.md) and [configure data retention](./setup.md#data-retention)
 - [Reference documentation](./reference.md)
diff --git a/docs/ai-coder/ai-bridge/monitoring.md b/docs/ai-coder/ai-bridge/monitoring.md
@@ -9,3 +9,54 @@ AI Bridge records the last `user` prompt, token usage, and every tool invocation
 We provide an example Grafana dashboard that you can import as a starting point for your metrics. See [the Grafana dashboard README](https://github.com/coder/coder/blob/main/examples/monitoring/dashboards/grafana/aibridge/README.md).
 
 These logs and metrics can be used to determine usage patterns, track costs, and evaluate tooling adoption.
+
+## Exporting Data
+
+AI Bridge interception data can be exported for external analysis, compliance reporting, or integration with log aggregation systems.
+
+### REST API
+
+You can retrieve AI Bridge interceptions via the Coder API with filtering and pagination support.
+
+```sh
+curl -X GET "https://coder.example.com/api/v2/aibridge/interceptions?q=initiator:me" \
+  -H "Coder-Session-Token: $CODER_SESSION_TOKEN"
+```
+
+Available query filters:
+
+- `initiator` - Filter by user ID or username
+- `provider` - Filter by AI provider (e.g., `openai`, `anthropic`)
+- `model` - Filter by model name
+- `started_after` - Filter interceptions after a timestamp
+- `started_before` - Filter interceptions before a timestamp
+
+See the [API documentation](../../reference/api/aibridge.md) for full details.
+
+### CLI
+
+Export interceptions as JSON using the CLI:
+
+```sh
+coder aibridge interceptions list --initiator me --limit 1000
+```
+
+You can filter by time range, provider, model, and user:
+
+```sh
+coder aibridge interceptions list \
+  --started-after "2025-01-01T00:00:00Z" \
+  --started-before "2025-02-01T00:00:00Z" \
+  --provider anthropic
+```
+
+See `coder aibridge interceptions list --help` for all options.
+
+## Data Retention
+
+AI Bridge data is retained for **60 days by default**. Configure the retention
+period to balance storage costs with your organization's compliance and analysis
+needs.
+
+For configuration options and details, see [Data Retention](./setup.md#data-retention)
+in the AI Bridge setup guide.
diff --git a/docs/ai-coder/ai-bridge/setup.md b/docs/ai-coder/ai-bridge/setup.md
@@ -94,3 +94,26 @@ AI Bridge can relay traffic to other OpenAI- or Anthropic-compatible services or
 
 > [!NOTE]
 > See the [Supported APIs](./reference.md#supported-apis) section below for precise endpoint coverage and interception behavior.
+
+## Data Retention
+
+AI Bridge records prompts, token usage, and tool invocations for auditing and
+monitoring purposes. By default, this data is retained for **60 days**.
+
+Configure retention using `--aibridge-retention` or `CODER_AIBRIDGE_RETENTION`:
+
+```sh
+coder server --aibridge-retention=90d
+```
+
+Or in YAML:
+
+```yaml
+aibridge:
+  retention: 90d
+```
+
+Set to `0` to retain data indefinitely.
+
+For duration formats, how retention works, and best practices, see the
+[Data Retention](../../admin/setup/data-retention.md) documentation.
