# 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.

| Field | Meaning |
| --- | --- |
| `success` | Domain success reported by the workflow |
| `status` | Usually `succeeded`, `partial`, or `failed` inside the workflow payload |
| `message` | Human-readable summary |
| `data` | Workflow data, keyed by URL for extraction |
| `errors` | Structured workflow errors |
| `warnings` | Degraded but usable conditions |
| `usage` | Metered usage details when available |
| `billing_state` | Billing disposition for the run |
| `telemetry_run_id` | Identifier for operational investigation |

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.

```python
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.

```python
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](/markdown/makra-sdk/v0.0.3-beta/extraction/design-a-schema).