Clairic field types: text, number, date, list, estimate and forecast

Fields, not questions

A decision model takes questions and picks from options you list. Choice, Score and Noul are its three shapes. An extraction model takes fields instead. Clairic, Cloudflare’s first, reads the input and fills in a typed value for each field.

A Clairic request has a state, the text to read, and fields, a map from field name to field spec. Every spec needs a type. Most also carry instructions, a plain sentence on what the field should contain. A field name starts with a letter or underscore and runs to 64 characters at most.

There is no cap on the number of fields. Fields that do not fit beside the state in one 8,192-token pass are split across parallel passes. The field specs bill as input tokens: in the docs’ invoice example they took 472 of 655.

Cloudflare’s concepts page groups the work into four jobs. Extraction returns a value printed in the input. Computation works one out from facts in the input. Estimation predicts a value the input does not settle. Forecasting predicts a value for each step of a future period. The nine types below cover all four.

The nine types at a glance

Every type also takes null_threshold, covered below.

text

A text answer is a span of the state: the exact characters, with their start and end offsets. It cannot return words that are not in the input. In the docs’ invoice example, invoice_number comes back as “INV-2291” with the span [8, 16].

Set the request option return_state_text to get back the text the spans index into.

number

A number is read from the input or worked out from it. decimals sets the precision from 0 to 6, integer forces a whole number, and unit is a label such as “USD”.

The docs’ invoice lists 4 pallets at $250.00 and $80.00 shipping. Ask for the total “including shipping” and Clairic returns 1080, a figure the invoice never states.

date, time and datetime

These three return dates and times in ISO form. A date can be computed too. The same invoice was issued on 2026-09-02, net 30, and due_date comes back as 2026-10-02.

For dates written without a year, the request option reference_date, an ISO date, anchors the year. Cloudflare’s concepts page gives a related tip: when a field depends on today’s date, put the date in the state rather than assume the model knows when the request runs.

duration

A duration is a length of time. unit must be one of seconds, minutes, hours, days, weeks, months or years, and the default is seconds. It takes integer and decimals like a number. Cloudflare’s blog example works out days_since_delivery as 11 days from two dates in a support email.

list

A list returns every match in input order, with one span per item. items is required and sets what the list holds: text, number or date. A number list takes decimals.

When nothing matches, a list comes back empty, not null. The invoice example’s contacts field returns “Dana Ruiz” and “Priya Shah” with their two spans.

estimate

An estimate predicts a value the input does not settle, such as how many days an invoice will take to be paid. It is the type to use when the honest answer is a range.

You must set min and max: numbers, or ISO dates for a date estimate. step sets the grid. It is a positive number (days, for a date estimate), or “month” or “year”. scale is linear by default, or log for values that span orders of magnitude, such as prices.

The answer is a distribution: value, mean, median, and an 80% interval from p10 to p90. The output also carries p_below and p_above; Cloudflare’s docs list them but do not define them as of 20 October 2026. The invoice example’s days_to_pay returns a median of 30 and an interval of 21 to 38.

An estimate always answers. The concepts page says estimates and forecasts “return predictions even when the input provides little information.” A wide interval is the sign that the input said little. The estimate glossary entry has the short version.

forecast

A forecast predicts a series of future values, one per step. It takes min and max like an estimate, a horizon of 1 to 64 steps, and an interval: step, minute, hour, day, week, month, quarter or year.

The output schema describes a steps field as “one estimate per step”. In the blog’s airport example, a one-day forecast returns value, median and p10 as arrays with one entry each. Cloudflare’s own blog calls forecasting “basic” and says it does not replace a time-series model trained on your data. See the forecast glossary entry.

p_null, guess and confidence

Single-value answers (text, number, date, time, datetime and duration) come back with four fields:

• value: the answer, or null when the model finds the input does not settle it.
• p_null: the probability that the value is not in the input.
• guess: what the model would have picked anyway. The blog says it “shows what the model would otherwise have picked.”
• confidence: the confidence score for the answer.

The invoice has no purchase order number. So po_number comes back with value null and p_null 1, while guess still holds “INV-2291”. Read p_null before you read guess, or that guess passes for an answer.

Estimates and forecasts have no p_null. Their uncertainty lives in the interval.

null_threshold

null_threshold is the p_null above which a field’s value comes back null. It must be above 0 and at most 1, and the default is 0.5.

Lower it for fields where a wrong value costs more than a missing one, such as an amount that triggers a payment. Raise it when you would rather review a doubtful value than lose it. guess is there either way, so a strict threshold drops nothing you cannot read back.

Request options

Two options sit under options, both off by default:

• include_quantiles adds all 99 percentiles to every estimate, under quantiles.
• return_state_text returns the text that spans index into.

What the types do not promise

Types and bounds shape the answer. They do not make it right. Cloudflare’s concepts page is plain about it: “A result can satisfy its type and constraints while still answering the question incorrectly.” Bounding a payment date to November gets you a November date even if the invoice is paid in December. Match your checks to the cost of a wrong value, and send anything that moves money past a person or a second source.

FAQ

How many field types does Clairic have?

Nine: text, number, date, time, datetime, duration, list, estimate and forecast. Text, number, the three date and time types and duration return one value with p_null, guess and confidence. A list returns every match. An estimate returns a distribution, and a forecast returns one estimate per future step.

What is the difference between a number and an estimate?

A number is read from the input or computed from facts in it, such as a total from line items. An estimate predicts a value the input does not settle, such as when an invoice will be paid. It needs min and max bounds and returns a median with an 80% interval.

What does null_threshold do?

It sets the p_null above which a field’s value comes back null. The default is 0.5 and it must be above 0 and at most 1. A lower threshold returns null more often. The model’s guess still comes back, so you can read what it would have picked.

Can a Clairic field return text that is not in the input?

Not as a text field. A text answer is a span of the state, with character offsets, so it is always a verbatim copy. Numbers, dates and durations can be computed, so those values may not appear in the input at all.

How many fields can one Clairic request have?

There is no upper limit. Fields that do not fit beside the state in one 8,192-token pass are split across parallel passes, and the answers come back together. Every field definition counts as input tokens, so a long schema costs more than the text it reads.