# Client

Python SDK 0.0.4 provides `Makra` and `AsyncMakra`. Both expose the same operations. Async methods are awaitable, and async stream methods return async iterators.

This documentation release covers Python SDK 0.0.4 only. Install the [`makra` package from PyPI](https://pypi.org/project/makra/). JavaScript is not part of the current documentation release.

## Constructor

```python
from makra import Makra

client = Makra(
    api_key=None,
    base_url=None,
    timeout=None,
    connect_timeout=None,
    stream_idle_timeout=None,
    max_retries=None,
    retry_backoff=None,
    default_headers=None,
)
```

Resolution order is explicit argument, environment value, then SDK default. Supported environment names are `MAKRA_API_KEY`, `MAKRA_BASE_URL`, `MAKRA_TIMEOUT`, and `MAKRA_MAX_RETRIES`.

Defaults are a 300 second request budget, 10 second connect timeout, 90 second stream idle timeout, two retries, and 0.5 second initial retry backoff. The production base URL is `https://api.makralabs.org`.

`default_headers` may contain application headers, but not `Api-Key`, `Content-Type`, `Accept`, `User-Agent`, `Idempotency-Key`, `Prefer`, or `Last-Event-ID`.

## Health methods

| Method | Result |
| --- | --- |
| `ping()` | Gateway health body |
| `ready()` | Gateway and result-storage readiness body |

## Workflow methods

| Method | Purpose |
| --- | --- |
| `extract(urls, schema, *, execution_mode, config, idempotency_key, timeout)` | Run an extraction and wait for its envelope |
| `schema(url, *, only_memoized, config, idempotency_key, timeout)` | Discover or read a page schema and wait |
| `extract_stream(urls, schema, *, execution_mode, config, idempotency_key)` | Submit extraction and iterate events |
| `schema_stream(url, *, only_memoized, config, idempotency_key)` | Submit schema discovery and iterate events |
| `submit_extract(urls, schema, *, execution_mode, config, idempotency_key)` | Return a `RunHandle` after admission |
| `submit_schema(url, *, only_memoized, config, idempotency_key)` | Return a `RunHandle` after admission |

`urls` must be a non-empty sequence of non-empty strings. Passing one string instead of a sequence is rejected. `schema` must be a non-empty mapping or list.

## Run methods

| Method | Purpose |
| --- | --- |
| `get_run(run_id)` | Fetch metadata, never the result payload |
| `list_runs(*, limit, cursor, feature, state)` | List non-archived runs newest first |
| `cancel_run(run_id)` | Request cancellation safely more than once |
| `wait_for_run(run_id, *, timeout, poll_interval, raise_on_failure)` | Poll to a terminal state |
| `stream_run_events(run_id, *, last_event_id)` | Attach to or resume a run stream |
| `get_run_result(run_id)` | Download the stored terminal payload |

## Run handles

`RunHandle` exposes `id`, `feature`, `state`, admission URLs, and the original admission mapping. It provides `refresh()`, `wait()`, `stream()`, `result()`, and `cancel()`.

`AsyncRunHandle` provides the same operations. `stream()` returns an async iterator. The other operations are awaitable.

Use [Options and configuration](/markdown/makra-sdk/v0.0.4-beta/reference/options-and-configuration) for request controls. The HTTP contract is published at [/openapi.yaml](/openapi.yaml).