Python SDK

The Python SDK ships in the same package as the CLI. If you haven’t installed or authenticated yet, follow the Overview first.

Quickstart

pip install cekura

from cekura import Cekura

# Reads CEKURA_API_KEY env var, or falls back to the OAuth session
# saved by `cekura auth login`. Pass api_key="..." to override.
client = Cekura()

# List agents
agents = client.agents.list(project_id=742)

# Fetch one
agent = client.agents.get(agent_id=123)

# Trigger a run
result = client.scenarios.run_text(
    agent_id=123,
    scenario_ids=[1, 2, 3],
)

Sync client

from cekura import Cekura

client = Cekura()

# List scenarios for an agent
scenarios = client.scenarios.list(agent_id=123)

# Update an agent
client.agents.update(agent_id=123, description="Updated by SDK")

# Pull production calls
calls = client.calls.list(project_id=742, page_size=50)
for c in calls.get("results", calls):
    print(c["id"], c.get("duration"))

Async client

For application code that’s already async (FastAPI, aiohttp, anyio, etc.), use AsyncCekura:

import asyncio
from cekura import AsyncCekura

async def main():
    async with AsyncCekura() as client:
        agents = await client.agents.list(project_id=742)
        for a in agents:
            print(a["id"], a["name"])

asyncio.run(main())

The async client mirrors the sync API method-for-method — anything you can do with Cekura you can do with await AsyncCekura(...).

Resource map

The client exposes one attribute per top-level resource. Each provides typed methods (list, get, create, update, delete) plus resource-specific actions:

client.agents              client.cron_jobs
client.scenarios           client.dashboards
client.metrics             client.test_sets
client.runs                client.metric_reviews
client.results             client.critical_metric_scenarios
client.calls               client.predefined_metrics
client.projects            client.phone_numbers
client.organizations       client.billing
client.personalities       client.api_keys
client.test_profiles       client.alerts
client.scenario_improvement_sessions
client.metric_failure_mode_insights
client.slack

Use dir(client) in a REPL or help(client.agents) to discover everything available.

Common patterns

Pull last 50 production calls

from cekura import Cekura

client = Cekura()
calls = client.calls.list(project_id=742, page_size=50)
for c in calls.get("results", calls):
    print(c["id"], c.get("duration"), c.get("call_ended_reason"))

Trigger an evaluation and poll until complete

import time
from cekura import Cekura

client = Cekura()
result = client.scenarios.run_text(
    agent_id=123,
    scenario_ids=[1, 2, 3],
)
run_id = result["run_id"]

while True:
    run = client.runs.get(run_id)
    if run["status"] in ("passed", "failed", "errored"):
        break
    time.sleep(5)

print("final status:", run["status"])

Bulk-update scenarios

from cekura import Cekura

client = Cekura()
client.scenarios.bulk_update(
    scenarios=[
        {"id": 101, "tags": ["regression"]},
        {"id": 102, "tags": ["smoke"]},
    ],
)

Create a metric programmatically

from cekura import Cekura

client = Cekura()
metric = client.metrics.create(
    agent_id=123,
    name="Booking confirmed",
    type="llm_judge",
    prompt="Did the agent confirm a booking and read back the date and time?",
)
print("created metric", metric["id"])

Configuration

The SDK resolves configuration in this order (first match wins):

Explicit argument — Cekura(api_key=..., api_url=...)
Environment variable — CEKURA_API_KEY, CEKURA_API_URL
Config file — ~/.cekura/config.toml (managed by the CLI)
Defaults — https://api.cekura.ai

This means a developer can cekura auth login once and any Python script on the same machine picks up the OAuth session automatically — no API key needed.

Troubleshooting

`Authentication failed`

OAuth path: the saved session expired. Re-run cekura auth login.
API key path: confirm CEKURA_API_KEY is set in the process environment, or pass Cekura(api_key=...) explicitly. Some endpoints (e.g. billing.info) require an org-scoped API key — OAuth bearer is not sufficient.

Rate limited (429)

The platform enforces per-plan rate limits. Add backoff between calls, batch where possible, or upgrade your plan. Check usage in Settings → API Usage.

Pagination

List endpoints return a paginated response shape: {"count": N, "next": url, "previous": url, "results": [...]}. Pass page= and page_size= to walk pages, or check results length to know when to stop.

CLI & SDK

Quickstart

Sync client

Async client

Resource map

Common patterns

Configuration

Troubleshooting

References

CLI guide

API Reference

​Quickstart

​Sync client

​Async client

​Resource map

​Common patterns

​Configuration

​Troubleshooting

​References

CLI guide

API Reference

Quickstart

Sync client

Async client

Resource map

Common patterns

Configuration

Troubleshooting

References