# Python SDK

Every method in the kestrel package, with its options and what it returns. Python 3.9 and later, sync and async.

```bash Terminal
pip install kestrel
```

## Kestrel

```python Python
Kestrel(api_key=None, default_repo=None, base_url=None, timeout_ms=60_000, max_retries=4)
```

`AsyncKestrel` takes the same options, and every method on it is awaitable.

## runs

### runs.create

```python Python
run = kestrel.runs.create(
    repo="acme/web-app",
    task="Fix the flaky checkout test",
    agent="claude-code",          # optional
    from_="web-app-seeded",       # optional snapshot; from is a keyword in Python
    routing={"floor": "medium"},  # optional
    evals={"repeat_tests": 20},   # optional
)
```

### run.steps and run.wait

```python Python
for step in run.steps():
    print(step.name, step.duration_ms)

result = run.wait()
print(result.status, result.pull_request.url if result.pull_request else None)
```

| Field | Type |
|---|---|
| `status` | `"pr_opened"`, `"needs_review"`, `"cancelled"` or `"failed"` |
| `pull_request` | `PullRequest(number, url)` or `None` |
| `gate` | Each check with its result and time |
| `usage` | `Usage(sandbox_minutes, tokens, cost_usd)` |

### runs.get, runs.list, runs.cancel, runs.trace

```python Python
kestrel.runs.get("run_8f2c")
kestrel.runs.list(repo="acme/web-app", status="queued", limit=20)
kestrel.runs.cancel("run_8f2c")
kestrel.runs.trace("run_8f2c")
```

## sandboxes

```python Python
sandbox = kestrel.sandboxes.create(repo="acme/web-app", timeout_ms=600_000)
sandbox.commands.run("npm test")
sandbox.files.write("notes.md", "...")
sandbox.pause()
kestrel.sandboxes.resume(sandbox.id)
sandbox.snapshot(name="web-app-seeded")
sandbox.kill()
```

## Async

```python Python
import asyncio
from kestrel import AsyncKestrel

async def main():
    kestrel = AsyncKestrel()
    runs = [await kestrel.runs.create(repo="acme/web-app", task=t) for t in tasks]
    results = await asyncio.gather(*(r.wait() for r in runs))

asyncio.run(main())
```

## Errors

Errors raise `kestrel.KestrelError`, with subclasses `AuthError`, `ForbiddenError`, `RateLimitedError` (with `retry_after`), `NotFoundError` and `ServerError`.