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. JavaScript is not part of the current documentation release.

Constructor

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 for request controls. The HTTP contract is published at /openapi.yaml.

Troubleshooting

Options and configuration