# SuperPenguin

> SuperPenguin is an AI spend attribution platform. Providers can each tell you what you spent with them, and several now publish their own split between coding-agent spend and API spend, but none of them knows your customers, features, teams, or pull requests. SuperPenguin connects every provider billing account into one total and then attributes that total to the thing in your business that caused it. SuperPenguin observes provider calls and reads provider billing APIs; it is not a proxy and is not in your request path.

## Products

- [Attribution](/attribution): Cost per customer, feature, and team
- [Coding ROI](/coding-roi): Coding agent spend, per pull request
- [One View](/one-view): Every provider bill, as one total

## Connect an AI agent with the CLI or MCP

- [SuperPenguin CLI setup and command examples](/docs/cli)
- CLI installer (macOS/Linux): curl -fsSL https://install.superpenguin.ai | sh
- CLI login: superpenguin auth login --native (interactive browser OAuth).
- CLI workflow: superpenguin context --agent, then superpenguin capabilities list --q "weekly spend" --agent and command help. Data commands use --agent for structured JSON.
- [MCP setup and agent instructions](/docs/mcp)
- [REST Agent API guide](/docs/agent-api): OAuth-authenticated programmatic access to the same organization-scoped operations.
- Remote Streamable HTTP endpoint: https://app.superpenguin.ai/api/mcp
- Authentication: OAuth in the user's browser; no API key or client secret is required.
- Agent workflow: call get_context first, use discover to load only relevant operation schemas, then call query with a discovered operationId.

An MCP-capable agent may configure the endpoint directly. It must pause for the human to sign in, choose a SuperPenguin organization, review scopes, and approve access. The connection inherits that user's current role in the selected organization.

## Key pages

- [LLM cost management](/llm-cost-management): what the category is (the practice of monitoring, attributing, controlling, and optimizing an organization's spending on large language models), and the two halves of AI spend it covers.
- [Pricing](/pricing): priced on managed AI spend, not per seat or per request.
- [Book a demo](/book-a-demo)
- [Security](/security)
- [Full product reference](/llms-full.txt)

## Provider Billing Profile Assets

- [Normative profile](/specs/provider-billing/v0.1/profile.md)
- [OpenAPI 3.1 contract](/specs/provider-billing/v0.1/openapi.yaml)
- [Conformance runner](/specs/provider-billing/v0.1/conformance.mjs)

# SuperPenguin Docs

- [SuperPenguin documentation](/docs): Track and investigate AI spend with SuperPenguin SDKs, the CLI, MCP, and the Agent API, or implement the Provider Billing API.
- [Connect an AI agent with MCP](/docs/mcp): Connect Claude Code, Cursor, ChatGPT, or another remote MCP client to your SuperPenguin workspace with OAuth.
- [Use the SuperPenguin CLI](/docs/cli): Investigate AI spend, provider billing, and coding usage from your terminal or an AI agent with the SuperPenguin CLI.
- [Agent API](/docs/agent-api): Use SuperPenguin's organization-scoped spend and account data programmatically through OAuth-authenticated REST resources.
- Company Setup
  - [Create a company workspace](/docs/getting-started/company-workspace): Set up the shared workspace where a company manages engineers, providers, and AI cost.
  - [Invite engineers](/docs/getting-started/invite-engineers): Add engineers to a company workspace and control who can view organization-wide AI Coding information.
  - [Set up AI Coding and PR Costs](/docs/getting-started/ai-coding-and-pr-costs): Understand the shared team setup, optional provider connections, and the extra GitHub step for pull-request attribution.
  - [Install SuperPenguin Desktop](/docs/getting-started/superpenguin-desktop): Email the Mac app to engineers, sign in, and begin syncing AI coding activity.
  - [Connect GitHub and enable PR Cost Attribution](/docs/getting-started/github-and-pr-costs): Connect repositories and combine pull-request data with engineers' Desktop activity.
- Getting Started
  - [Quickstart](/docs/quickstart/overview): Install a SuperPenguin SDK, wrap a provider client, and attribute your first AI request.
  - [Create an API key](/docs/quickstart/api-key): Create a SuperPenguin API key and keep it server-side.
  - [Add attribution metadata](/docs/quickstart/metadata): Attach customer, feature, team, and prompt metadata so every request is queryable in the dashboard.
- Hosted OpenTelemetry
  - [Hosted OpenTelemetry ingestion](/docs/otel/hosted-ingestion): Send OTLP/HTTP JSON GenAI traces directly to SuperPenguin without installing an SDK.
  - [OpenRouter Broadcast](/docs/otel/openrouter-broadcast): Configure OpenRouter Webhook Broadcast to send OTLP JSON request telemetry to SuperPenguin.
  - [Coding session transcripts](/docs/otel/coding-session-transcripts): Opt in to keep full Claude Code and Codex session transcripts for 90 days, on laptops and in Claude Code cloud environments.
- SDKs
  - Python
    - [Python SDK overview](/docs/sdk/python/overview): Install and initialize the SuperPenguin Python SDK for per-request AI cost tracking.
    - [Python providers](/docs/sdk/python/providers): Wrap OpenAI, Azure OpenAI, Cohere, Anthropic, Gemini, Bedrock, LiteLLM, Deepgram, ElevenLabs, and OpenAI Realtime with the Python SDK.
    - [Python advanced usage](/docs/sdk/python/advanced): Tracing, batch jobs, content capture controls, and Python configuration reference.
  - TypeScript
    - [TypeScript SDK overview](/docs/sdk/typescript/overview): Install and initialize @superpenguin/js for server-side AI cost attribution.
    - [TypeScript providers](/docs/sdk/typescript/providers): Wrap OpenAI, Azure OpenAI, Cohere, Anthropic, Gemini, Bedrock, Deepgram, ElevenLabs, and Realtime with @superpenguin/js.
    - [Vercel AI SDK](/docs/sdk/typescript/vercel-ai-sdk): Track generateText and streamText with SuperPenguin helpers for the Vercel AI SDK.
    - [Agent SDKs and dynamic metadata](/docs/sdk/typescript/agents): Attribute Vercel, OpenAI Agents, LangGraph, Pi, OpenCode and custom harness model calls to each customer and run.
    - [OpenTelemetry](/docs/sdk/typescript/opentelemetry): Submit existing OpenTelemetry spans to SuperPenguin for cost attribution.
- Concepts
  - [Attribution](/docs/concepts/attribution): How SuperPenguin attributes AI spend with structured metadata across providers.
  - [Billing reconciliation](/docs/concepts/reconciliation): Compare SDK-estimated AI costs against provider-billed invoices.
  - [Pricing and cost semantics](/docs/concepts/pricing-and-costs): How SuperPenguin estimates SDK costs and how that differs from provider-billed amounts.
  - [Plans and entitlements](/docs/concepts/plans-and-entitlements): Current SuperPenguin plan prices, workspace limits, and feature availability.
  - [Workspace roles and AI Coding visibility](/docs/concepts/team-roles-and-visibility): Understand owner, member, Viewer, and Policy administrator access.
  - [Content capture and privacy](/docs/concepts/content-capture): Opt-in, encrypted prompt and completion capture, and how to group multi-turn conversations.
  - [Batch and service-tier pricing](/docs/concepts/batch-and-tier-pricing): Track native Batch API jobs and regional or service-tier rate cards.
- Provider Integrations
  - [Connect an existing provider](/docs/providers/connect-a-provider): Connect OpenAI, Anthropic, and other provider accounts so SuperPenguin can pull billed usage.
  - Billing Integration Guide
    - [Build a billing integration](/docs/providers/billing-integration/overview): Implement the SuperPenguin FOCUS AI Provider Profile for usage and billed-cost exports.
    - [Authentication](/docs/providers/billing-integration/authentication): Scoped bearer tokens and OAuth 2.0 Authorization Code with PKCE for provider billing exports.
    - [Usage data](/docs/providers/billing-integration/usage-data): Export complete AI usage meters with UTC windows, pagination, and stable record IDs.
    - [Cost data](/docs/providers/billing-integration/cost-data): Export provider-reported billed costs with final, provisional, and correction semantics.
    - [Conformance testing](/docs/providers/billing-integration/conformance): Run the dependency-free Provider Billing conformance runner against your sandbox.
- Provider Billing API Reference
  - [Provider Billing API reference](/docs/api-reference/introduction): Exact endpoint parameters and schemas generated from the FOCUS AI Provider Profile OpenAPI contract.
  - Provider billing
    - [Describe export capabilities for the authorized account.](/docs/api-reference/provider-billing/getFinOpsCapabilities)
    - [Export complete metered usage over a half-open UTC window.](/docs/api-reference/provider-billing/listFinOpsUsage)
    - [Export provider-reported billed costs over a half-open UTC window.](/docs/api-reference/provider-billing/listFinOpsCosts)
- [Troubleshooting](/docs/troubleshooting): Fix common SuperPenguin SDK, attribution, and provider-connection issues.