Read an extraction response

The SDK returns the API response envelope without unwrapping it. Read outcome, data, diagnostics, and billing information separately.

Stable envelope fields

Successful workflow responses can contain these fields.

Do not confuse HTTP success with complete extraction. A multi-URL run can produce useful data for some URLs and errors for others.

Extract by URL, not by position

data is a mapping from URL to schema-shaped result. Read it using the submitted URL.

from typing import Any, Mapping


def successful_items(response: Mapping[str, Any]) -> dict[str, Any]:
    data = response.get("data")
    if not isinstance(data, Mapping):
        return {}
    return {str(url): value for url, value in data.items() if value is not None}

A failed URL can remain present with a None value. Preserve that distinction in batch pipelines. Dropping it silently loses the identity of the failed work item.

Treat warnings as data-quality signals

Warnings do not fail a run. They can report missing selector matches, fallback use, alignment degradation, unavailable validation evidence, storage-version invalidation, or schema truncation.

from typing import Any, Mapping


def require_clean_result(response: Mapping[str, Any]) -> None:
    warnings = response.get("warnings") or []
    if warnings:
        raise RuntimeError(f"Extraction completed with warnings: {warnings!r}")

Production policy should be more selective than this example. A missing optional field may be acceptable. Sibling alignment degradation on financial rows may not be.

Preserve raw values

Makra returns document strings without trimming, type coercion, currency parsing, or date interpretation. A schema field declared as a number can still contain a formatted string. Convert values in a separate step so extraction errors and parsing errors remain distinguishable.

Keep investigation identifiers

Store telemetry_run_id and, for durable workflows, the public run ID beside your own job identifier. They are the shortest path from an application failure to a specific workflow execution.

Next, design a schema.