> This page is for Gateway. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.merge.dev/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server. # Extractions > Call extraction models on Gateway with POST /v1/extractions: name the fields you want, set each one's type, and read typed values with confidence, source spans, and distributions. Extraction models read a state you supply, such as an invoice, email, or contract, and return one typed value per field you name. Use them to fill a record from a document when you need a date, number, or list you can store, not text to parse. Each value comes with a confidence and, for text, the exact span it came from, so you can decide which values to trust without asking a chat model for JSON. ## Send an extraction request Send `state`, the text to read, and `fields`, a map of named fields whose keys come back as the keys of `answers`. Each field's `type` sets the type of its value. **`cURL`** ```bash title="cURL" curl https://api-gateway.merge.dev/v1/extractions \ -H "Authorization: Bearer $MERGE_GATEWAY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "cloudflare/clairic", "state": "Invoice INV-2291 from Northwind Supply, issued 2026-09-02, net 30. 4 pallets at $250.00 each, shipping $80.00. Contact: Dana Ruiz, Priya Shah.", "fields": { "invoice_number": {"type": "text"}, "due_date": {"type": "date", "instructions": "Issue date plus the net payment days"}, "total": {"type": "number", "decimals": 2, "unit": "USD", "instructions": "Pallets plus shipping"}, "contacts": {"type": "list", "items": "text"}, "days_to_pay": {"type": "estimate", "min": 0, "max": 120, "step": 1, "instructions": "How many days until this is paid?"} } }' ``` **`Python`** ```python title="Python" import os, requests response = requests.post( "https://api-gateway.merge.dev/v1/extractions", headers={"Authorization": f"Bearer {os.environ['MERGE_GATEWAY_API_KEY']}"}, json={ "model": "cloudflare/clairic", "state": "Order 5521 shipped on March 4 by UPS Ground to alice@acme.com.", "fields": { "order_id": {"type": "text"}, "shipped_on": {"type": "date"}, "carrier": {"type": "text"}, }, "reference_date": "2026-03-10", }, ) answers = response.json()["answers"] print(answers["shipped_on"]["value"], answers["shipped_on"]["confidence"]) ``` The cURL request returns: ```json { "object": "extraction", "model": "clairic", "vendor": "cloudflare", "answers": { "invoice_number": {"type": "text", "value": "INV-2291", "guess": "INV-2291", "confidence": 0.99998, "p_null": 0.000006, "span": [8, 16]}, "due_date": {"type": "date", "value": "2026-10-02", "guess": "2026-10-02", "confidence": 0.99997, "p_null": 0.000001}, "total": {"type": "number", "value": 1080, "guess": 1080, "confidence": 0.99996, "p_null": 0.0000006}, "contacts": {"type": "list", "value": ["Dana Ruiz", "Priya Shah"], "spans": [[120, 129], [131, 141]], "confidence": 0.99987}, "days_to_pay": {"type": "estimate", "value": 30, "mean": 29.97, "median": 30, "p10": 27, "p90": 32, "p_below": 0.0000004, "p_above": 0.0000019} }, "truncated": false, "state_text": null, "usage": {"input_tokens": 478, "output_tokens": 0, "total_tokens": 478, "passes": 2, "cost": 4.78e-05} } ``` `value` is null when the input doesn't determine the field. `p_null` is the probability of that, and `guess` is the model's best value even when `value` is null, so use `guess` only where a wrong value costs less than a missing one. `span` and `spans` are character offsets into `state`. The model can compute as well as copy: `due_date` adds the 30 net days to the issue date, and `total` adds the pallets to shipping. ## Choose a model | Model | Field types | Images and `options` | Input price | Zero data retention | | --------------------- | ----------------------------------------------------------------- | -------------------- | ------------------------- | ------------------- | | `cloudflare/clairic` | All | Yes | \$0.10 per million tokens | Yes | | `scaledown/extract-1` | `text`, `date`, `time`, `datetime`, and lists of `text` or `date` | No | \$0.05 per million tokens | No | Use `cloudflare/clairic` when you need numbers, durations, estimates, forecasts, images, or confidence. `scaledown/extract-1` returns `type` and `value` only, with no confidence or spans, and costs half as much for plain text and dates. Output is \$0 on both, and `usage.cost` reports the cost in USD. ## Reference | Type | Value | Options | | -------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- | | `text` | A string, with `span` | | | `number` | A number | `unit`, `decimals` (0 to 6), `integer` | | `date`, `time`, `datetime` | An ISO 8601 string | | | `duration` | A number in `unit`: `seconds` (the default), `minutes`, `hours`, `days`, `weeks`, `months`, or `years` | `unit`, `decimals`, `integer` | | `list` | An array, with `spans` | Required `items`: `text`, `number`, or `date`. `decimals` for numbers. | | `estimate` | A single value plus `mean`, `median`, `p10`, `p90`, `p_below`, and `p_above` | Required `min` and `max`, both numbers or both ISO dates. `step` and `scale`. | | `forecast` | One estimate per step, in `steps` | Required `min`, `max`, and `horizon` (1 to 64 steps). `interval`, `step`, and `scale`. | Every field takes optional `instructions` and `null_threshold`, the probability of null above which `value` is null (0.5 by default). Field names start with a letter or underscore and run up to 64 characters. | Field | Notes | | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | Required. An extraction model, such as `cloudflare/clairic`. Gateway `@alias/...` IDs return `400 alias_not_supported`. | | `state` | Text to read. Can be empty only when `images` are sent. | | `fields` | Required. 1 to 100 fields. | | `images` | Up to 4 PNG, JPEG, or WebP images, as `data:` URLs or `{"content_type", "base64"}` objects. 4 MiB each and 8 MiB in total, decoded. Remote URLs aren't accepted. | | `reference_date` | ISO date that anchors relative dates such as "next Tuesday" and dates written without a year | | `options` | `include_quantiles` adds 99 percentiles to estimates. `return_state_text` returns the text that spans index into, as `state_text`. | | `vendor` | Pin the execution vendor. A mismatch returns `400 vendor_unavailable`. | | `customer` | [Customer](/merge-gateway/embedded-routing-stack/customers) UUID to scope the key, budget, and usage to | | Limit or error | Value | | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | Context window | 65,536 tokens on `cloudflare/clairic`. Longer input is cut from the end, returns `truncated: true`, and bills at the cap. | | Unknown fields, such as `stream` | `422`, rather than being ignored | | A field option its type doesn't take, a `list` without `items`, or an `estimate` or `forecast` without `min` and `max` | `422` before any vendor call | | A `forecast` without `horizon` | `422` | | A field type `scaledown/extract-1` doesn't support | `400 unsupported_field_type` | | `images` or `options` sent to `scaledown/extract-1` | `400 unsupported_params` | | An extraction model sent to another endpoint, or another model sent here | `400 unsupported_endpoint_for_model`, naming the endpoint to use | | [DLP](/merge-gateway/security/data-loss-prevention) match | `422 blocked_by_dlp_policy`, including for organizations in redact mode | > **Fields can multiply the input you pay for** > > `cloudflare/clairic` reads `state` alongside as many fields as fit in one 8,192-token pass, and splits the rest across more passes. Each pass reads `state` again, so `usage.input_tokens` counts it once per pass and `usage.passes` says how many there were. Ask for the fields you need in one request rather than one request per field, and keep `instructions` short. Extraction models don't stream and take no sampling parameters. Organizations with [zero data retention](/merge-gateway/security/zero-data-retention) can call `cloudflare/clairic` but not `scaledown/extract-1`. `GET /v1/models` lists extraction models with `output: ["extraction"]`, paged at 50 by default, so pass `limit` (up to 500) when you search. ## Next steps #### [Decisions](/merge-gateway/capabilities/decisions) Typed answers to questions about a state, such as a choice or a score #### [Errors](/merge-gateway/errors) Every error code Gateway returns and what to do