Authentication
- All write endpoints require a Bearer token in the Authorization header:
+ All API endpoints require a Bearer token in the Authorization header.
+ To obtain an API key, register at{" "}
+
+ agentlens.vectry.tech/register
+
+ , log in, and create a key in{" "}
+ Settings → API Keys
+ .
{`Authorization: Bearer your-api-key`}
+
+
+ Rate limits:{" "}
+ API usage is governed by your billing tier. The Free plan allows 20
+ sessions per day. Starter ($5/month) allows 1,000 sessions per
+ month. Pro ($20/month) allows 100,000 sessions per month. One trace
+ equals one session for billing purposes. Manage your plan in{" "}
+ Settings → Billing
+ . See{" "}
+
+ Authentication & Billing
+ {" "}
+ for details.
+
+
+
+ Authentication & Billing
+
+
+ AgentLens cloud requires an account to access the dashboard and ingest
+ traces. This page covers registration, API key management, billing
+ tiers, and session counting.
+
+
+
+ Registration
+
+ To use AgentLens cloud, create an account at{" "}
+
+ agentlens.vectry.tech/register
+
+ . You will need to provide an email address and password. Once
+ registered, log in at{" "}
+
+ agentlens.vectry.tech
+ {" "}
+ to access the dashboard.
+
+
+ The dashboard requires authentication -- there is no anonymous access.
+ All features including trace viewing, analytics, and settings are
+ available only after login.
+
+
+
+
+ API keys
+
+ API keys authenticate your SDKs and integrations when sending traces
+ to AgentLens. Keys are generated per-user in the dashboard.
+
+
+ Creating an API key
+
+
+ - Log in to the AgentLens dashboard.
+ -
+ Navigate to{" "}
+
+ Settings → API Keys
+
+ .
+
+ -
+ Click Create API Key,
+ give it a name, and copy the generated key.
+
+ -
+ Store the key securely. It will not be shown again after you leave
+ the page.
+
+
+
+ Using your API key
+
+
+ Pass the key to the SDK during initialization, or set it as the{" "}
+
+ AGENTLENS_API_KEY
+ {" "}
+ environment variable. The SDKs will pick it up automatically.
+
+
+
+ Security note:{" "}
+ Treat API keys like passwords. Do not commit them to version control.
+ Use environment variables or a secrets manager in production.
+
+
+
+
+ Billing tiers
+
+ AgentLens cloud offers three billing tiers. One trace equals one
+ session for billing purposes.
+
+
+
+
+
+ |
+ Plan
+ |
+
+ Price
+ |
+
+ Sessions
+ |
+
+ Details
+ |
+
+
+
+
+ | Free |
+ $0 |
+ 20 sessions/day |
+
+ No credit card required. Ideal for experimentation and
+ personal projects.
+ |
+
+
+ | Starter |
+ $5/month |
+ 1,000 sessions/month |
+
+ For individual developers with moderate tracing needs.
+ |
+
+
+ | Pro |
+ $20/month |
+ 100,000 sessions/month |
+
+ For teams and production workloads with high trace volume.
+ |
+
+
+
+
+
+
+ Session counting
+
+ A session is equivalent to a single trace sent to the AgentLens API.
+ Each call to{" "}
+
+ POST /api/traces
+ {" "}
+ that includes one trace counts as one session, regardless of how many
+ spans, decision points, or events are inside that trace.
+
+
+ If you batch multiple traces in a single API call, each trace in the
+ batch counts as a separate session.
+
+
+
+
+
+ Managing your subscription
+
+
+ To view your current plan, upgrade, downgrade, or manage payment
+ methods, go to{" "}
+
+ Settings → Billing
+ {" "}
+ in the dashboard. Changes take effect immediately. If you downgrade
+ mid-cycle, you retain access to the higher tier until the end of the
+ current billing period.
+
+
+
+
+ Self-hosted instances
+
+ If you are running a self-hosted AgentLens instance, registration with
+ the hosted SaaS service is not required. Self-hosted deployments
+ manage their own authentication and have no session limits or billing
+ tiers. See the{" "}
+
+ Self-Hosting guide
+ {" "}
+ for setup instructions.
+
+
+
Next steps
diff --git a/apps/web/src/app/docs/page.tsx b/apps/web/src/app/docs/page.tsx
index e49d144..ae189c8 100644
--- a/apps/web/src/app/docs/page.tsx
+++ b/apps/web/src/app/docs/page.tsx
@@ -22,6 +22,12 @@ const sections = [
description:
"Understand Traces, Spans, Decision Points, and Events — the four building blocks of AgentLens.",
},
+ {
+ title: "Authentication & Billing",
+ href: "/docs/authentication-billing",
+ description:
+ "Register for an account, manage API keys, and understand billing tiers and session limits.",
+ },
],
},
{
diff --git a/apps/web/src/app/docs/self-hosting/page.tsx b/apps/web/src/app/docs/self-hosting/page.tsx
index 1118a73..a758467 100644
--- a/apps/web/src/app/docs/self-hosting/page.tsx
+++ b/apps/web/src/app/docs/self-hosting/page.tsx
@@ -14,6 +14,9 @@ export default function SelfHostingPage() {
AgentLens is open source and designed to be self-hosted. You can deploy
it with Docker in minutes, or run from source for development.
+ Self-hosted instances do not require registration with the AgentLens
+ cloud service and are not subject to any session limits or billing
+ tiers.
diff --git a/packages/opencode-plugin/README.md b/packages/opencode-plugin/README.md
index b6d6432..19973f7 100644
--- a/packages/opencode-plugin/README.md
+++ b/packages/opencode-plugin/README.md
@@ -8,6 +8,8 @@ OpenCode plugin for AgentLens — trace your coding agent's decisions, tool call
## Requirements
- OpenCode >= 1.1.0
+- An AgentLens account -- register at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register)
+- An API key created in **Settings > API Keys** in the AgentLens dashboard
## Install
@@ -44,7 +46,7 @@ Add the plugin to your OpenCode configuration at `~/.config/opencode/opencode.js
}
```
-Set your API key:
+Set your API key (create one at **Settings > API Keys** in the [AgentLens dashboard](https://agentlens.vectry.tech)):
```bash
export AGENTLENS_API_KEY="your-api-key"
@@ -52,6 +54,8 @@ export AGENTLENS_API_KEY="your-api-key"
The plugin activates automatically when OpenCode starts. No code changes required.
+Each OpenCode session counts as one trace (one session) for billing purposes. See the [billing documentation](https://agentlens.vectry.tech/docs/authentication-billing) for plan details.
+
## What Gets Captured
The plugin hooks into OpenCode's event system and records:
diff --git a/packages/sdk-python/README.md b/packages/sdk-python/README.md
index d8299e8..7eed085 100644
--- a/packages/sdk-python/README.md
+++ b/packages/sdk-python/README.md
@@ -12,6 +12,8 @@ AgentLens is an observability SDK for AI agents. Unlike generic LLM tracing tool
## Quick Start
+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
```bash
pip install vectry-agentlens
```
@@ -19,7 +21,7 @@ pip install vectry-agentlens
```python
import agentlens
-# Initialize once at startup
+# Initialize with the API key from Settings > API Keys
agentlens.init(api_key="your-api-key")
# Trace any function with a decorator
@@ -160,7 +162,7 @@ Initialize the SDK. Call once at application startup.
```python
agentlens.init(
- api_key="your-api-key", # Required. Your AgentLens API key.
+ api_key="your-api-key", # Required. Create at Settings > API Keys in the dashboard.
endpoint="https://...", # API endpoint (default: https://agentlens.vectry.tech)
flush_interval=5.0, # Seconds between batch flushes (default: 5.0)
max_batch_size=10, # Traces per batch before auto-flush (default: 10)
@@ -168,6 +170,8 @@ agentlens.init(
)
```
+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
### `agentlens.trace()`
Decorator or context manager that creates a trace (or a nested span if already inside a trace).
@@ -264,13 +268,25 @@ The SDK is lightweight and non-blocking. Traces are serialized and batched in a
## Dashboard
-View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech):
+View your traces at [agentlens.vectry.tech](https://agentlens.vectry.tech) (login required):
- **Decision Trees** - Visualize the full decision path of every agent run
- **Analytics** - Token usage, cost breakdowns, latency percentiles
- **Real-time Streaming** - Watch agent decisions as they happen
- **Session Grouping** - Track multi-turn conversations by session ID
+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
## Development
```bash
diff --git a/packages/sdk-ts/README.md b/packages/sdk-ts/README.md
index 4cd63b6..307d198 100644
--- a/packages/sdk-ts/README.md
+++ b/packages/sdk-ts/README.md
@@ -13,10 +13,12 @@ npm install agentlens-sdk
## Quick Start
+First, create an account at [agentlens.vectry.tech/register](https://agentlens.vectry.tech/register) and generate an API key in **Settings > API Keys** in the dashboard.
+
```typescript
import { init, TraceBuilder, shutdown } from "agentlens-sdk";
-// Initialize the SDK
+// Initialize with the API key from Settings > API Keys
init({
apiKey: "your-api-key",
endpoint: "https://agentlens.vectry.tech/api",
@@ -104,17 +106,31 @@ Pass `InitOptions` to `init()`:
```typescript
init({
- apiKey: "your-api-key", // Required. Your AgentLens API key.
+ apiKey: "your-api-key", // Required. Create at Settings > API Keys in the dashboard.
endpoint: "https://...", // API endpoint. Defaults to AgentLens cloud.
maxBatchSize: 100, // Max items per batch before auto-flush.
flushInterval: 5000, // Auto-flush interval in milliseconds.
});
```
+You can also set the API key via the `AGENTLENS_API_KEY` environment variable instead of passing it directly.
+
## Transport
The SDK ships with `BatchTransport`, which batches payloads and flushes them on an interval or when the batch size threshold is reached. This is used internally by `init()` — you typically do not need to instantiate it directly.
+## Billing
+
+Each trace counts as one session for billing. AgentLens cloud offers three tiers:
+
+| Plan | Price | Sessions |
+|------|-------|----------|
+| Free | $0 | 20 sessions/day |
+| Starter | $5/month | 1,000 sessions/month |
+| Pro | $20/month | 100,000 sessions/month |
+
+Manage your subscription in **Settings > Billing**. Self-hosted instances have no session limits.
+
## Documentation
Full documentation: [agentlens.vectry.tech/docs/typescript-sdk](https://agentlens.vectry.tech/docs/typescript-sdk)