Using a large general-purpose LLM to pull a few fields out of a receipt or a support ticket is often overkill: it’s slow, it costs output tokens, and you still have to parse and validate free-form JSON. On 18 November 2026 Cloudflare released an updated Clairic and a new, smaller Clairic-flash, two purpose-built extraction models that return typed answers with confidence scores, and made both open-weight.
This tutorial explains what the models do, how the typed field API works, and how to call it from Python and a Cloudflare Worker, with a simple confidence-based review pattern. Sources: Cloudflare’s announcement post and the Clairic model docs.
What Clairic is (and isn’t)
Clairic is a small, task-specific model. Instead of chatting, you give it some input (the state, plus optional images or PDFs) and a schema of typed fields. It returns an answer for each field, along with probabilities such as how likely the field is to be missing.
Key facts from Cloudflare:
- Two sizes: Clairic (27B parameters) at
@cf/cloudflare/clairic, and Clairic-flash (9B) at@cf/cloudflare/clairic-flash. - Inputs: text, plus up to four images or PDF pages in total per request. PDF support is new in this release.
- Typed outputs: text answers come back as exact spans of your input with character offsets; numbers, dates, lists and estimates have their own types.
- Pricing: billed on input tokens only. Clairic is $0.24 per million input tokens and Clairic-flash $0.10, with a promotion putting both at $0.10 until 1 December 2026.
- Open weights: Cloudflare says full weights for both models are published on Hugging Face.
Cloudflare’s own evals show the new models well ahead of their preview on its internal tests, and median latencies of roughly 150–700 ms depending on the workload and model size. These are self-reported numbers with no public extraction benchmark yet, as Cloudflare itself notes, so test on your own documents.
What changed under the hood
For ordinary text and number fields, the redesigned Clairic uses what Cloudflare calls parallel slot autoregressive generation: each field generates its own tokens and stops at its own end marker, while all fields advance together in the serving batch. Special heads handle estimates, forecasts, durations, calculated dates and arithmetic.
The field types
The request body has three main parts: model, state and fields. Based on the documentation examples, you can use:
| Type | Use for | Extra options |
|---|---|---|
text |
Names, IDs, short strings (returned as spans) | instructions |
number |
Amounts, quantities | decimals, unit, instructions |
date |
Dates, including calculated ones | instructions |
list |
Repeated values like contacts | items |
estimate |
Predictions with a range | min, max, step, instructions |
You can also pass reference_date (an ISO date) to anchor dates written without a year.
Calling Clairic from Python
You need a Cloudflare account ID and an API token with Workers AI permissions.
import os
import requests
ACCOUNT_ID = os.environ["CLOUDFLARE_ACCOUNT_ID"]
TOKEN = os.environ["CLOUDFLARE_AUTH_TOKEN"]
URL = f"https://api.cloudflare.com/client/v4/accounts/{ACCOUNT_ID}/ai/run/@cf/cloudflare/clairic"
payload = {
"model": "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": "Amount due including shipping",
},
"contacts": {"type": "list", "items": "text"},
"po_number": {"type": "text", "instructions": "Purchase order number"},
},
}
resp = requests.post(URL, headers={"Authorization": f"Bearer {TOKEN}"}, json=payload, timeout=30)
resp.raise_for_status()
data = resp.json()
print(data)
In the docs’ sample response, invoice_number comes back as INV-2291 with a character span, due_date as 2026-10-02 (worked out from the issue date and terms), total as 1080, and po_number as null, because the invoice has no purchase order number and the model’s p_null for it is 1.
Depending on whether you call the REST API directly, the answers may be wrapped in Cloudflare’s usual result envelope, so a defensive accessor helps:
result = data.get("result", data)
answers = result["answers"]
print(answers["total"]["value"], answers["total"]["confidence"])
A confidence-based review pattern
Because every answer carries a confidence and a probability of being null, you can automate the easy cases and send the rest to a human:
def triage(answers: dict, min_conf: float = 0.95) -> tuple[dict, list[str]]:
accepted, review = {}, []
for name, ans in answers.items():
conf = ans.get("confidence")
if ans.get("value") is None:
accepted[name] = None # model is confident the field is absent
elif conf is not None and conf >= min_conf:
accepted[name] = ans["value"]
else:
review.append(name)
return accepted, review
accepted, needs_review = triage(answers)
print("auto:", accepted)
print("check manually:", needs_review)
Tune min_conf on a labelled sample of your own documents; there’s no universal threshold.
Estimates: predictions with a range
The estimate type returns a distribution rather than a single guess. For example, asking how many days a customer will take to pay:
payload["fields"] = {
"days_to_pay": {
"type": "estimate",
"min": 0,
"max": 120,
"step": 1,
"instructions": "Days after issue until this invoice is paid",
}
}
The documented response includes median, mean, and an 80% interval via p10 and p90, which is far more useful for planning than a single number.
Calling Clairic from a Worker
Inside a Cloudflare Worker with an AI binding, the call is a single line:
export interface Env {
AI: Ai;
}
export default {
async fetch(request, env): Promise<Response> {
const { text } = await request.json<{ text: string }>();
const result = await env.AI.run("@cf/cloudflare/clairic-flash", {
model: "clairic",
state: text,
fields: {
order_id: { type: "text", instructions: "Customer order number" },
product: { type: "text", instructions: "Product the customer is writing about" },
refund_amount: {
type: "number", decimals: 2, unit: "USD",
instructions: "Refund amount the customer asks for",
},
},
});
return Response.json(result);
},
} satisfies ExportedHandler<Env>;
The clairic-flash endpoint is the cheaper 9B variant; switch the model path to @cf/cloudflare/clairic for the higher-quality 27B model. The model field in the body stays "clairic", as in Cloudflare’s documented examples; check the model page for each endpoint’s exact schema.
Practical limits to plan for
- Context: the Clairic docs list a 65,536-token context window; oversized prompts are rejected.
- Images: up to four images (4 MiB each, 8 MiB total); remote URLs are not accepted, so embed them.
- Passes and billing: each
textfield gets its own pass, and every pass re-reads the full state and images. Many text fields on a long document therefore cost more input tokens;usage.passestells you how many passes ran. - Preview label: the docs page still describes the model as being in preview, so expect changes.
Key takeaways
- Clairic (27B) and Clairic-flash (9B) are open-weight extraction models from Cloudflare, available on Workers AI.
- You define typed fields and get spans, values, confidences and null probabilities back, with no free-form JSON parsing.
- Billing is input tokens only, with promo pricing until 1 December 2026.
- Use confidence thresholds to automate the easy fields and route uncertain ones to humans.
Read Cloudflare’s launch post and the model documentation for the full schema.
