Python SDK Pro

Send events from any Python server runtime using a project API key. Works with Django, FastAPI, Flask, Celery workers, scheduled jobs, and anything else that runs Python and can make outbound HTTPS calls.

Paste to your agent

Wire Clamp Analytics into this Python app.

Read https://clamp.sh/docs/sdk/python.

1. ASK ME for a Clamp project API key (format `sk_proj_...`) and add it to the env as CLAMP_API_KEY. Wait for confirmation. Do not invent a key.
2. Install `clamp-analytics` (pip / poetry / uv, whichever this project uses).
3. Initialize once at app startup:
     from clamp_analytics import init
     init(project_id="<the project id>", api_key=os.environ["CLAMP_API_KEY"])
   For Django: settings.py. For FastAPI: lifespan. For Flask: app factory.
4. Track the primary conversion event from the right handler. For Stripe webhooks: in checkout.session.completed and invoice.paid:
     from clamp_analytics import track, Money
     track("subscription_started", anonymous_id=session.client_reference_id, properties={"plan": plan, "total": Money(amount, currency)})
   Amounts in major units (29.00, not 2900). Currency ISO 4217 uppercase.
5. ASK ME to trigger a test event and confirm it appears at https://clamp.sh/dashboard. If not, check server logs for clamp_analytics errors and debug with me before claiming success.
6. Stop and report: which handler you wired, where CLAMP_API_KEY is read from, and whether the test event landed in the dashboard.

Install

pip install clamp-analytics

Python 3.9+ supported. The package depends only on httpx for the HTTP call.

Use an API key that starts with sk_proj_ from Settings → API Keys. Keys are scoped to one project. Set it as an environment variable; never commit it.

Quick start

from clamp_analytics import init, track, Money

init(project_id="proj_xxx", api_key=os.environ["CLAMP_API_KEY"])

# Simple event
track("signup", properties={"plan": "pro", "method": "email"})

# Link a server event to a browser visitor
track(
    "subscription_started",
    anonymous_id="aid_xxx",
    properties={"plan": "pro", "total": Money(29.00, "USD")},
)

API

init(project_id, api_key, endpoint=None)

Initializes the SDK. Call once at process startup. Stores config in module-level state; subsequent track() calls use it.

endpoint is optional and overrides the default https://api.clamp.sh. Use this for self-hosted Clamp deployments or integration testing.

track(name, properties=None, anonymous_id=None, timestamp=None)

Sends a server event. Returns True on success.

• name: event name string. Examples: "signup", "subscription_started", "feature_used".
• properties: optional dict. Values may be str, int, float, bool, or Money. No nested dicts (other than Money) and no arrays.
• anonymous_id: optional string. Links the server event to a browser visitor. Read the browser's anonymous ID via the JS SDK's getAnonymousId()and pass it through your auth flow (e.g. Stripe's client_reference_id).
• timestamp: optional. Pass a datetime (timezone-aware preferred; naive datetimes are assumed UTC) or an ISO 8601 string. If omitted, the SDK uses the current UTC time.

Raises ClampHTTPError on a non-2xx response or ClampNotInitializedError if init()wasn't called.

Money(amount, currency)

A typed monetary value. Use it for revenue, refunds, taxes — anywhere a currency-denominated amount belongs.

track("purchase", properties={
    "plan": "pro",
    "total": Money(29.00, "USD"),
    "tax": Money(4.35, "USD"),
})

amount is in major units (29.00, not 2900). currency is an ISO 4217 code (uppercase, three letters).

Framework integrations

Django

Initialize in settings.py so the singleton is ready for any view, signal, or management command.

import os
from clamp_analytics import init

init(
    project_id=os.environ["CLAMP_PROJECT_ID"],
    api_key=os.environ["CLAMP_API_KEY"],
)

from clamp_analytics import track

def signup_complete(request):
    user = create_user(request)
    track("signup", anonymous_id=request.COOKIES.get("clamp_aid"), properties={
        "plan": user.plan,
        "method": "email",
    })
    return redirect("/welcome")

FastAPI

Initialize in the lifespan handler so the SDK is ready before the first request.

import os
from contextlib import asynccontextmanager
from fastapi import FastAPI
from clamp_analytics import init, track

@asynccontextmanager
async def lifespan(app: FastAPI):
    init(
        project_id=os.environ["CLAMP_PROJECT_ID"],
        api_key=os.environ["CLAMP_API_KEY"],
    )
    yield

app = FastAPI(lifespan=lifespan)

@app.post("/checkout")
async def checkout(payload: CheckoutPayload):
    session = create_stripe_session(payload)
    track("checkout_started", anonymous_id=payload.anon_id, properties={
        "plan": payload.plan,
    })
    return {"url": session.url}

Flask

Initialize in the app factory.

import os
from flask import Flask
from clamp_analytics import init, track

def create_app():
    app = Flask(__name__)
    init(
        project_id=os.environ["CLAMP_PROJECT_ID"],
        api_key=os.environ["CLAMP_API_KEY"],
    )
    return app

Celery / background workers

For high-throughput webhook handlers, defer the track() call to a background task so the request handler returns fast.

from celery import Celery
from clamp_analytics import init, track, Money

celery = Celery(__name__)

@celery.task
def report_subscription_started(plan, amount, currency, anonymous_id):
    init(...)  # idempotent; called once per worker
    track("subscription_started", anonymous_id=anonymous_id, properties={
        "plan": plan,
        "total": Money(amount, currency),
    })

Errors and retries

The SDK is synchronous and raises on failure. There are no automatic retries. If you want fire-and-forget behaviour, wrap the call yourself:

import logging
from clamp_analytics import track, ClampError

def safe_track(*args, **kwargs):
    try:
        return track(*args, **kwargs)
    except ClampError:
        logging.exception("failed to send to Clamp")

Webhook handlers that absolutely must not block on Clamp should defer to a Celery / RQ / Dramatiq queue.

Linking browser and server events

Pass the anonymous ID from the browser to your API, then include it in server-side calls. Events from both sides then share a visitor. See the linking pattern on the server-side docs page; the same pattern applies in Python.

Links

• PyPI: clamp-analytics
• Source: github.com/clamp-sh/analytics-python