Skip to navigation
Request capabilities

Extractions

Pull typed values out of text and images, with confidence for each one

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 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?"}
    }
  }'

The cURL request returns:

{
  "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

ModelField typesImages and optionsInput priceZero data retention
cloudflare/clairicAllYes$0.10 per million tokensYes
scaledown/extract-1text, date, time, datetime, and lists of text or dateNo$0.05 per million tokensNo

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

TypeValueOptions
textA string, with span
numberA numberunit, decimals (0 to 6), integer
date, time, datetimeAn ISO 8601 string
durationA number in unit: seconds (the default), minutes, hours, days, weeks, months, or yearsunit, decimals, integer
listAn array, with spansRequired items: text, number, or date. decimals for numbers.
estimateA single value plus mean, median, p10, p90, p_below, and p_aboveRequired min and max, both numbers or both ISO dates. step and scale.
forecastOne estimate per step, in stepsRequired 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.

FieldNotes
modelRequired. An extraction model, such as cloudflare/clairic. Gateway @alias/... IDs return 400 alias_not_supported.
stateText to read. Can be empty only when images are sent.
fieldsRequired. 1 to 100 fields.
imagesUp 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_dateISO date that anchors relative dates such as “next Tuesday” and dates written without a year
optionsinclude_quantiles adds 99 percentiles to estimates. return_state_text returns the text that spans index into, as state_text.
vendorPin the execution vendor. A mismatch returns 400 vendor_unavailable.
customerCustomer UUID to scope the key, budget, and usage to
Limit or errorValue
Context window65,536 tokens on cloudflare/clairic. Longer input is cut from the end, returns truncated: true, and bills at the cap.
Unknown fields, such as stream422, rather than being ignored
A field option its type doesn’t take, a list without items, or an estimate or forecast without min and max422 before any vendor call
A forecast without horizon422
A field type scaledown/extract-1 doesn’t support400 unsupported_field_type
images or options sent to scaledown/extract-1400 unsupported_params
An extraction model sent to another endpoint, or another model sent here400 unsupported_endpoint_for_model, naming the endpoint to use
DLP match422 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 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

Typed answers to questions about a state, such as a choice or a score

Errors

Every error code Gateway returns and what to do