Get started

Quickstart: Python SDK

About 5 minutes. You need a Python app that calls OpenAI or Anthropic with their official Python packages.

1. Create a workspace and a key

  1. Create an account with email or Google.
  2. Name your workspace. One workspace is one team or product.
  3. Choose Python SDK, choose the environment (usually Production), and press Create key.
  4. Copy the key. It looks like zx_<id>_<secret>.<salt> and is shown once.

The part after the dot is the salt. It is made in your browser and Zexl never receives it. The SDK uses it to hash prompts locally, so nobody, including Zexl, can match a hash to text.

2. Install and turn it on

bash
pip install zexl
bash
export ZEXL_API_KEY="zx_..."

Add one import at your app's entry point, before the OpenAI or Anthropic client is created:

python
import zexl.auto  # records OpenAI and Anthropic calls; prompts never leave the process

That is the whole setup. Typical entry points: main.py or app.py (FastAPI, Flask), wsgi.py or asgi.py (Django), the worker start module (Celery), the handler module (AWS Lambda).

If you load .env in code (for example with python-dotenv), put the import after load_dotenv().

3. Make a call and watch it arrive

Run your app so it makes one model call. The setup page shows the call within a few seconds. Waste analysis follows within about 3 minutes.

python
import zexl

with zexl.feature("support-reply"):      # which product feature made the calls
    ...

with zexl.run("research", feature="report-builder"):  # one unit of agent work
    ...

zexl.set_customer(account.id)            # your customer's id, never an email

Without labels, the feature is the module.function that made the call, and agent loops are grouped into runs automatically. See Features, runs and customers.

Short-lived processes

Serverless functions, scripts and CLI tools should call zexl.flush() before they exit, so the last records are sent.

Settings

VariableMeaningDefault
ZEXL_API_KEYYour key. Requirednone
ZEXL_ENVEnvironment label. Ignored when the key has its own environmentproduction
ZEXL_DISABLED1 turns the SDK off completelyoff
ZEXL_OPENAI_STREAM_USAGE1 asks OpenAI for token usage on streamed chat callsoff

What is covered

ProviderCalls
OpenAIchat.completions.create, .parse, .stream; responses.create, .parse; streaming; sync and async
Anthropicmessages.create, .parse, .stream; beta.messages; streaming; sync and async

Your calls are never blocked or changed. If Zexl is down, records are dropped and your app carries on. zexl.status() shows whether capture is on and how many records were sent.