Documentation

1) Getting Started

CostLynx tracks AI usage by workspace (organization), project, environment, provider, and model. For fastest onboarding, create one ingestion key and send one sample event.

• Sign in and select a single workspace (not “All organizations”).
• Go to Settings → Configure and create an ingestion key.
• Create or verify project/environment slugs (recommended for attribution).
• Send your first event to POST /api/v1/usage/ingest.
• Open Overview, Usage, and Costs dashboards to confirm ingestion.

2) Quickstart (5 minutes)

1. Create an ingestion key in Settings → Configure.
2. Set environment variables in your app: $BASE_URL, $COSTLYNX_INGESTION_KEY.
3. Send one event with a stable requestId (idempotency key).
4. Confirm the event appears in dashboard totals.

{
  "ok": true,
  "inserted": 1,
  "skipped": 0
}

// If cost could not be estimated (missing pricing + no estimatedCostUsd):
{
  "ok": true,
  "inserted": 1,
  "skipped": 0,
  "warnings": ["1 event(s) stored without a cost estimate. Provide estimatedCostUsd or add pricing for the model."]
}

3) Usage Ingestion (Canonical)

Canonical endpoint: POST /api/v1/usage/ingest. Auth uses an ingestion key in X-API-Key.

• Required per event: provider, model, requestId.
• requestId — use your LLM API's own response ID (e.g. OpenAI's chatcmpl-...), or generate a UUID. Must be unique per event within your workspace.
• project and environment are slug strings (e.g. customer-support, prod) — not names or IDs. Create them first in Settings → Configure.
• Token fields (inputTokens, outputTokens, cachedTokens) are numeric and non-negative; default to 0.
• Duplicate requestId in the same workspace is silently skipped and counted as skipped in the response — safe to retry.
• gemini provider alias is accepted and normalized to google internally.
• Supports single event body or { "events": [...] } (1 to 100 events per request).
• Query ?strict=1 returns 400 if a project/environment slug is provided but not found in your workspace.

curl -X POST "$BASE_URL/api/v1/usage/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $COSTLYNX_INGESTION_KEY" \
  -d '{
    "provider": "openai",
    "model": "gpt-4o-mini",
    "inputTokens": 1200,
    "outputTokens": 450,
    "requestId": "req_openai_001",
    "project": "customer-support",
    "environment": "prod"
  }'

curl -X POST "$BASE_URL/api/v1/usage/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $COSTLYNX_INGESTION_KEY" \
  -d '{
    "provider": "anthropic",
    "model": "claude-3-5-sonnet",
    "inputTokens": 900,
    "outputTokens": 300,
    "estimatedCostUsd": 0.0123,
    "requestId": "req_anthropic_001",
    "project": "customer-support",
    "environment": "prod"
  }'

curl -X POST "$BASE_URL/api/v1/usage/ingest" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $COSTLYNX_INGESTION_KEY" \
  -d '{
    "provider": "gemini",
    "model": "gemini-1.5-pro",
    "inputTokens": 800,
    "outputTokens": 260,
    "estimatedCostUsd": 0.0101,
    "requestId": "req_gemini_001",
    "project": "internal-copilot",
    "environment": "prod"
  }'

4) Providers

• OpenAI: connection tests + sync-ready usage pull, plus API ingestion support.
• Anthropic: API ingestion supported; provider sync currently returns no usage rows.
• Google Gemini: API ingestion supported; provider sync currently returns no usage rows.
• Azure OpenAI: API ingestion supported; provider sync currently returns no usage rows.

For non-OpenAI providers, treat API ingestion as the source of truth for attribution and dashboards.

5) API Reference

POST /api/v1/usage/ingest — Auth: ingestion key. Stores SDK/API usage events.

GET /api/v1/org — Auth: Clerk session. Returns active workspace profile and billing summary fields.

GET|POST /api/v1/provider-connections — Auth: Clerk + concrete org. List/create provider links.

PATCH|DELETE /api/v1/provider-connections/:id — Update/remove a provider connection in active org.

POST /api/v1/provider-connections/:id/test — Run provider credential check; returns { ok, message }.

GET|POST /api/budgets — List/create budgets for active org.

PATCH|DELETE /api/budgets/:id — Update/delete one budget.

GET|POST /api/alerts/evaluate — Cron-secured anomaly evaluation.

GET|POST /api/alerts/rules and GET|PATCH|DELETE /api/alerts/rules/:id — Manage alert rules.

POST /api/stripe/create-checkout-session — Auth: Clerk + concrete org. Creates Starter/Growth checkout.

POST /api/stripe/create-portal-session — Auth: Clerk + concrete org. Opens Stripe billing portal for subscribed orgs.

6) Budgets & Alerts

• Budgets track monthly spend and forecast against configured amount.
• Budget status bands: on track, warning (80%+), over budget (100%+).
• Alert rules evaluate spend anomalies using rolling historical windows.
• Alert evaluation runs via cron every 15 minutes (UTC-based evaluation windows).
• Notifications are deduped per rule and time window to avoid duplicate sends.

Expect slight delay due to ingestion timing and cron cadence; alerts are eventually consistent, not real-time streaming.

7) Billing & Plans

• Starter: USD $79/month.
• Growth: USD $599/month.
• Checkout + portal require Stripe environment configuration.
• Webhook events sync subscription status into workspace billing state.
• If Stripe is disabled, UI remains informational and billing actions safely return unavailable responses.

Subscription syncing is driven by webhook events: checkout.session.completed, customer.subscription.updated, and customer.subscription.deleted.

8) Troubleshooting / FAQ

• 400 Validation failed: verify required fields and request payload schema before retrying.
• 401/403: use the correct credential type for the endpoint (ingestion key for ingestion routes, session auth for dashboard routes).
• Warnings in response: the event was accepted, but cost estimation was incomplete. Send estimatedCostUsd or use a provider/model with configured pricing.
• No dashboard data: confirm the active workspace, ingestion key scope, and date filters match your ingested events.
• Duplicate retries: reuse the same requestId for retried requests so idempotency can deduplicate safely.
• Billing unavailable: validate Stripe environment variables and webhook delivery for your workspace.