Skip to main content
Use this guide to connect a TypeScript or Python agent runtime to Pylva, starting from no account. Prefer to hand the whole integration to a coding agent? See Set up Pylva with an AI agent - one prompt does steps 3-6 for you. If you need to confirm whether your stack is automatic, callback-based, or manual, see Supported Integrations.

1. Choose a plan and create your account

Open pylva.com/pricing, choose Pro or Scale, and sign in with GitHub, Google, or an email magic link. There is no separate signup form or password. A new workspace remains in plan selection until Stripe Checkout starts its 14-day trial. Enterprise workspaces are activated through the sales process (see Plans and limits). A brand-new workspace shows a Get started checklist on the dashboard with a one-click Create API key button - the fastest path through step 2.

2. Create an API key

Open pylva.com/settings/keys (it lands on Settings -> API keys after sign-in; you must be the workspace owner). Click Create key. Copy the plaintext key from the save-your-key dialog immediately - it is shown once - and store it as PYLVA_API_KEY in your runtime secret store. New keys look like pv_live_{8 hex}_{32 hex}. The SDK never reads environment variables on its own; you pass the key to init explicitly in step 4. One key covers everything: SDK telemetry, rules, pricing, budget sync, custom pricing, and data import (see API keys). If init rejects the key or telemetry logs a key error, see Troubleshooting.

3. Install the SDK

4. Initialize the SDK

Call init at process startup, before serving traffic - provider calls made before init are not recorded.

TypeScript

Python

The default cloud endpoint is https://api.pylva.com. Self-hosted deployments can pass an endpoint override. Prefer to self-host or inspect the data path? See Open Source And Hosted.

5. Attribute calls to a customer and step

TypeScript

Python

If the provider call succeeds but no event appears, see Troubleshooting.

6. Verify your setup

Before or after wiring code, you can confirm the key works with a safe read - 200 means valid, 401 means the key is wrong or revoked:
The SDK flushes telemetry in the background, about every 5 seconds by default. For a short script that exits immediately, flush before exit.

TypeScript

Python

Events appear in the dashboard within a few seconds of a flush. On a new workspace, the Get started checklist is replaced by live cost data when the first event arrives - you should see customer acme-corp and step evaluate. If not, use Troubleshooting. For a raw curl smoke test of the ingest endpoint, see Submit telemetry events.

7. Check the dashboard

After events arrive, use the dashboard to review:
  • Total cost and cost by customer.
  • Expensive agent steps.
  • Unknown pricing tasks that need a pricing rule.
  • Rule events, warnings, and alerts.

Production checklist

  • Use opaque customer_id values.
  • Use stable step labels such as retrieve_context, evaluate, or summarize.
  • Do not send prompts, completions, emails, phone numbers, or raw messages in telemetry metadata.
  • Review Security And Data Handling before sending production data.
  • Configure pricing for any non-LLM metrics before relying on margin reports.
  • Review Controls Workflow before activating hard stops, routing, or failover.
  • Review Billing Workflow before turning customer usage into invoices.
  • Know your plan’s event cap and what happens at the limit: Plans and limits.
  • Keep Troubleshooting nearby for first-run key, flush, pricing, and budget errors.