Documentation

Everything you need to integrate usage tracking and billing into your AI application.

The typescript npm package is currently in invite-only beta.

Contents

Quick Start Dashboard Usage Plan Management Usage Tracking Stripe Setup Stripe Integration Error Handling

Quick Start

1. Installation

Install the Parmot SDK:

pip install parmot

2. Set up API Keys

Get your API keys and set them as environment variables:

.env

# Add to your .env file
PARMOT_API_KEY="parmot_your_api_key_here"
OPENAI_API_KEY="your_openai_api_key_here"
ANTHROPIC_API_KEY="your_anthropic_api_key_here"
COHERE_API_KEY="your_cohere_api_key_here"

💡 Get your Parmot API key: Sign up at the dashboard and create a new API key in the API Keys section.

3. Track Your First API Call

Basic Usage

from parmot import TrackedOpenAI

client = TrackedOpenAI(
    api_key="your_openai_api_key",
    parmot_api_key="your_parmot_api_key"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{
        "role": "user", 
        "content": "Hello, world!"
    }],
    user_id="user_123"
)

print(response.choices[0].message.content)

✅ That's it! Your API call is now tracked with cost and token usage. Usage limits will be automatically enforced based on the user's plan.

Dashboard Usage

Creating Plans

Create subscription plans with token and cost limits through the dashboard:

Navigate to the Dashboard
Go to the "Plans" section
Click "Create Plan"
Set your plan name, limits, and description
Save the plan

Plan Settings:

Monthly Token Limit: Maximum tokens per month (optional)
Monthly Cost Limit: Maximum cost per month in USD (optional)
Rate Limit (per minute): Maximum requests per minute (optional)
Rate Limit (per hour): Maximum requests per hour (optional)
Rate Limit (per day): Maximum requests per day (optional)
Description: Plan description for your reference

Managing Users

View and manage all your users from the Users section:

View real-time usage statistics
Assign users to different plans
Monitor usage against plan limits
Delete users and all their data

Plan Management

Creating Plans Programmatically

Create Plan

from parmot import ParmotClient

parmot = ParmotClient()

plan = parmot.create_end_user_plan(
    name="Pro",
    monthly_token_limit=1000000,
    monthly_cost_limit=50.00,
    description="Pro tier with 1M tokens/month"
)

print(f"Created plan with ID: {plan.plan_id}")

Assigning Users to Plans

Assign Plan

# Assign user to a plan
parmot.assign_end_user_to_plan("user_123", "Pro")

# Check user's current plan
plan = parmot.get_end_user_plan_assignment("user_123")
if plan:
    print(f"User is on {plan.name} plan")
else:
    print("User has no assigned plan")

Getting Usage Summary

Usage Summary

# Get usage summary for a specific user
summary = parmot.get_end_user_usage_summary("user_123")

print(f"Total cost: ${summary.total_cost}")
print(f"This month: ${summary.current_month_cost}")
print(f"Total requests: ${summary.total_requests}")
print(f"Total tokens: ${summary.total_tokens}")

# Get usage summary for all users (admin only)
all_usage = parmot.get_end_user_usage_summary()
print(f"Total platform cost: ${all_usage.total_cost}")

Usage Tracking

OpenAI Support

Both streaming and non-streaming responses are automatically tracked:

OpenAI Usage

# Streaming responses are automatically tracked
stream = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "Count to 10"}],
    stream=True,
    user_id="user_123"
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
        
# Usage is automatically recorded when stream completes

Anthropic Support

Full support for Anthropic's Messages API:

Anthropic Usage

from parmot import TrackedAnthropic

client = TrackedAnthropic(
    api_key="your_anthropic_api_key",
    parmot_api_key="your_parmot_api_key"
)

# Non-streaming
response = client.messages.create(
    max_tokens=100,
    messages=[{"role": "user", "content": "Hello!"}],
    model="claude-3-5-haiku-20241022",
    user_id="user_123"
)

print(response.content[0].text)

# Streaming
stream = client.messages.create(
    max_tokens=100,
    messages=[{"role": "user", "content": "Tell me a joke."}],
    model="claude-3-5-haiku-20241022",
    user_id="user_123",
    stream=True
)

for event in stream:
    if hasattr(event, "delta") and hasattr(event.delta, "text"):
        print(event.delta.text, end="")

Cohere Support

Support for Cohere's Chat API:

Cohere Usage

from parmot import TrackedCohere

client = TrackedCohere(
    api_key="your_cohere_api_key",
    parmot_api_key="your_parmot_api_key"
)

# Non-streaming
response = client.chat(
    model="command-r-08-2024",
    messages=[{"role": "user", "content": "Hello!"}],
    user_id="user_123"
)

print(response.message.content[0].text)

# Streaming
stream = client.chat_stream(
    model="command-r-08-2024",
    messages=[{"role": "user", "content": "Tell me a joke."}],
    user_id="user_123"
)

for event in stream:
    if hasattr(event, "delta") and hasattr(event.delta, "message"):
        if hasattr(event.delta.message, "content"):
            if hasattr(event.delta.message.content, "text"):
                print(event.delta.message.content.text, end="")

Supported Providers

Provider	Status	Modalities	Notes
OpenAI	Supported	Text, Vision	Chat Completions API (Beta and Responses coming soon).
Anthropic	Supported	Text	Chat completions API
OpenRouter	Supported	Text, Vision	Chat completions API
Cohere	Supported	Text	Chat API
AWS Bedrock	Coming Soon	-	-
Databricks	Coming Soon	-	-

Stripe Setup

Create Stripe Products and Prices

Before creating checkout sessions, you need to set up your products and prices in Stripe:

Create Stripe Product and Price

import stripe
import os
from dotenv import load_dotenv

load_dotenv()
stripe.api_key = os.getenv("STRIPE_SECRET_KEY")

# Create Stripe product
product = stripe.Product.create(
    name="Pro Plan",
    description="Pro plan with 50k tokens per month"
)

# Create Stripe price for $50/month
price = stripe.Price.create(
    unit_amount=5000,  # $50.00 in cents
    currency="usd",
    recurring={"interval": "month"},
    product=product.id,
)

print(f"Price ID: {price.id}")  # Save this for your checkout sessions

💡 Save the Price ID: You'll need the returned price ID for creating checkout sessions. You can also create products and prices through the Stripe dashboard.

Stripe Integration

Create Subscription Checkout Sessions

Use Parmot's built-in Stripe integration to create checkout sessions that automatically handle plan assignments:

Create Checkout Session with Parmot

from flask import Flask, redirect
from parmot import ParmotClient

app = Flask(__name__)
parmot = ParmotClient()

@app.route('/subscribe/<end_user_id>')
def subscribe(end_user_id):
    # Create checkout session with Parmot integration
    checkout_data = parmot.create_stripe_checkout_session(
        price_id="price_1234567890",  # Your existing Stripe price ID
        end_user_id=end_user_id,
        parmot_plan_name="Pro",
        success_url="https://yourapp.com/success",
        cancel_url="https://yourapp.com/cancel",
        parmot_fallback_plan_name="Free"
    )
    
    # Redirect to Stripe checkout
    return redirect(checkout_data['url'])

💡 Pro tip: The create_stripe_checkout_session method automatically handles metadata setup and creates the proper mapping between Stripe subscriptions and Parmot plans. Users will be automatically assigned to the specified plan when payment succeeds.

Webhook Setup

You must handle Stripe webhook events in your application to ensure proper handling of subscription updates.

Stripe Webhook Handler

@app.route('/stripe/webhook', methods=['POST'])
def stripe_webhook():
    payload = request.data
    sig_header = request.headers.get('stripe-signature')
    event = stripe.Webhook.construct_event(payload, sig_header, "whsec_your_secret")
    message, status_code = parmot.handle_stripe_event(stripe_event=event)
    return message, status_code

⚠️ Important: Configure these webhook events in your Stripe dashboard:invoice.payment_succeededinvoice.payment_failedcustomer.subscription.deletedcustomer.subscription.updated

Automatic Plan Management

With Parmot's Stripe integration, users will be automatically:

Payment Success

Moved to paid plan with increased limits when payment succeeds

Payment Failure

Moved to fallback plan when payment fails or subscription ends

Error Handling

Usage and Rate Limit Errors

Handle usage and rate limit errors gracefully:

Error Handling

from parmot import TrackedOpenAI, ParmotEndUserUsageLimitError, ParmotEndUserRateLimitError

client = TrackedOpenAI()

try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello!"}],
        user_id="user_123"
    )
except ParmotEndUserUsageLimitError as e:
    print(f"Usage limit exceeded: {e}")
    print(f"Current usage: {e.current_usage}")
    print(f"Limit: {e.limit}")
    print(f"Limit type: {e.limit_type}")
    # Handle limit exceeded - maybe upgrade user plan
except ParmotEndUserRateLimitError as e:
    print(f"Rate limit exceeded: {e}")
    print(f"Retry after: {e.retry_after} seconds")
except Exception as e:
    print(f"Other error: {e}")

Error Types

Error	Description
ParmotEndUserUsageLimitError	The end user's token/cost limit has been exceeded
ParmotEndUserRateLimitError	The end user's rate limit has been exceeded
ParmotEndUserBannedError	The end user was banned (by you) from making API calls
ParmotUsageLimitError	Your monthly usage logging limit has been exceeded
ParmotAPIError	General API error
ParmotNotFoundError	Resource not found
ParmotValidationError	Request validation failed

Ready to get started?

Start tracking usage and managing user limits today with our easy-to-use SDKs.

Get Started Free Book a Demo