# Extract typed fields

Source: <https://everruns.com/docs/api/operations/extract_typed_fields/>

[Docs](https://everruns.com/docs/)/[API reference](https://everruns.com/docs/api/)/[Models & integrations](https://everruns.com/docs/api/groups/models-integrations/)/Extract typed fields

# Extract typed fields

Preview

Connect model providers, discover models and configure MCP servers, search providers and plugins.

Public APIRequires an organization-owned provider and an enabled extraction model

POST`/v1/extractions`

See [authentication](https://everruns.com/docs/sre/runbooks/authentication/) for credentials and permissions.

## Request Bodyrequired

Media typeapplication/json

A configured org catalog model and its extraction input. Provider/model selection inside `input` is rejected; the catalog identity is authoritative.

object

**input**

required

Source content and typed fields; nested provider and model selectors must be absent.

object

**assets**

Defensive runtime ceiling: 32 assets and 32 MiB total encoded data. Individual providers and the HTTP API may impose lower limits.

object

**_key_**

additional properties

Inline asset; URLs are deliberately not fetched by the runtime.

object

**data_base64**

required

Nonempty standard base64 content, without a data URL prefix.

string

**format**

required

Encoding of the supplied bytes; support depends on the selected provider.

string

Allowed values: png jpg jpeg webp pdf

**type**

One of:

* string

  Optional media category. PDF requires document; other formats require image when specified.

  string

  Allowed values: image document

* null

  null

**fields**

required

Nonempty map of field names to typed extraction specifications; names must not be blank.

object

**_key_**

additional properties

A typed field specification. Constructors select a shape; validation rejects options which do not apply to it before any provider call.

object

**decimals**

Requested decimal precision, at most six, for a number, duration or list of numbers.

integer | null format: int32

**horizon**

Required number of forecast values, from 1 through 64; invalid for other field types.

integer | null format: int32

**instructions**

Field-specific extraction guidance, which may reference named assets.

string | null

**integer**

Request integer precision for a number, duration or list of numbers.

boolean | null

**interval**

One of:

* string

  Required spacing between forecast values; invalid for other field types.

  string

  Allowed values: step minute hour day week month quarter year

* null

  null

**items**

One of:

* string

  Required element type for lists; invalid for other field types.

  string

  Allowed values: text number date

* null

  null

**max**

One of:

* unknown

  One of:

  * number

    A finite numeric endpoint.

    number format: double

  * string

    An ISO calendar date endpoint (YYYY-MM-DD).

    string

* null

  A finite numeric endpoint.

  number format: double

* number

  An ISO calendar date endpoint (YYYY-MM-DD).

  string

* string

  null

**min**

One of:

* unknown

  One of:

  * number

    A finite numeric endpoint.

    number format: double

  * string

    An ISO calendar date endpoint (YYYY-MM-DD).

    string

* null

  A finite numeric endpoint.

  number format: double

* number

  An ISO calendar date endpoint (YYYY-MM-DD).

  string

* string

  null

**null_threshold**

Requested null-suppression threshold, finite and within 0..=1. Providers may impose stricter limits.

number | null format: double

**scale**

One of:

* string

  Optional estimate or forecast scale. Logarithmic numeric bounds must be positive.

  string

  Allowed values: linear log

* null

  null

**step**

One of:

* unknown

  One of:

  * number

    A finite, positive numeric resolution.

    number format: double

  * string

    A month or year resolution, valid only with date bounds.

    string

    Allowed values: month year

* null

  A finite, positive numeric resolution.

  number format: double

* number

  A month or year resolution, valid only with date bounds.

  string

  Allowed values: month year

* string

  null

**type**

required

Requested output shape; determines which field options are valid.

string

Allowed values: text number date time datetime duration list estimate forecast

**unit**

Requested value unit. Duration units are seconds, minutes, hours, days, weeks, months or years.

string | null

**model**

Optional nonempty provider model identifier; the Server selects its model outside this input.

string | null

**provider**

Optional explicit provider account for Framework routing; the Server rejects this override.

string | null

**provider_options**

Provider-specific options, without routing credentials or headers.

object

**_key_**

additional properties

**reference_date**

Optional ISO calendar date (YYYY-MM-DD) for interpreting relative dates.

string | null

**session_id**

Optional caller-supplied session identifier forwarded by supporting providers.

string | null

**state**

Source text and extraction context. May be empty when inline assets are supplied.

string

**trace**

Optional trace metadata forwarded by supporting providers.

**user**

Optional caller-supplied user identifier forwarded by supporting providers.

string | null

**model_id**

required

Enabled extraction-capable model ID from the current organization’s catalog.

string

## Responses

200Typed extraction values, evidence and usage

### 200

Typed extraction values, evidence and usage

Media typeapplication/json

Validated extraction results, keyed by the requested field names.

object

**answers**

required

Exactly one typed answer per requested field, keyed by the original field names.

object

**_key_**

additional properties

One typed answer with optional provider-reported evidence and uncertainty. Missing probabilities remain unknown; a null value is not replaced by its guess.

object

**confidence**

Optional provider-reported answer confidence, within 0..=1; absence means unknown, not certainty.

number | null format: double

**confidences**

Optional per-list-item confidence values within 0..=1, aligned with value items or a retained guess; null entries are unknown.

Array\<number | null> | null

**guess**

Optional typed candidate retained even when value is null; not an automatic replacement for value.

**mean**

Optional distribution mean for an estimate, or horizon-aligned means for a forecast, using the field value type.

**median**

Optional distribution median for an estimate, or horizon-aligned medians for a forecast, using the field value type.

**p10**

Optional tenth percentile for an estimate, or horizon-aligned percentiles for a forecast, using the field value type.

**p90**

Optional ninetieth percentile for an estimate, or horizon-aligned percentiles for a forecast, using the field value type.

**p\_above**

Optional provider-reported probability above the requested upper bound, within 0..=1.

number | null format: double

**p\_below**

Optional provider-reported probability below the requested lower bound, within 0..=1.

number | null format: double

**p\_null**

Optional provider-reported probability of no answer, within 0..=1.

number | null format: double

**quantiles**

Optional provider-specific quantile data for an estimate or forecast, preserved as JSON.

**source**

One of:

* string

  Optional source media category; image and document answers may have no textual span.

  string

  Allowed values: text image document

* null

  null

**span**

Optional half-open \[start, end] evidence range in Unicode code points of returned state_text or the original state.

Array\<integer> | null

**spans**

Optional per-list-item evidence ranges, aligned with value items or a retained guess; null entries indicate missing evidence.

Array\<Array\<integer> | null> | null

**spell_confidence**

Optional provider-reported spelling confidence, within 0..=1.

number | null format: double

**steps**

Optional provider-specific distribution step data for an estimate or forecast, preserved as JSON.

**type**

required

Output shape matching the requested field type.

string

Allowed values: text number date time datetime duration list estimate forecast

**unit**

Provider-reported unit of the extracted value.

string | null

**value**

required

Typed extracted value, or null when absent or suppressed. Forecast arrays match the requested horizon.

**id**

Optional provider-assigned extraction result identifier.

string | null

**model**

required

Model identifier reported for the extraction.

string

**provider**

Optional provider identifier associated with the result.

string | null

**state_text**

Optional returned source text used for evidence offsets; when absent, offsets refer to the original state.

string | null

**truncated**

Whether the provider reports that it did not read the whole input; defaults to false if omitted.

boolean

**usage**

Provider usage details; defaults to zero token counts and absent optional metrics when omitted.

object

**cost**

Optional finite, nonnegative provider-reported cost; no cost is inferred when absent.

number | null format: double

**image_tokens**

Optional token count attributed to image inputs.

integer | null format: int64

**input_tokens**

Provider-reported input token count; defaults to zero if omitted.

integer format: int64

**output_tokens**

Provider-reported output token count; defaults to zero if omitted.

integer format: int64

**passes**

Optional number of extraction passes reported by the provider.

integer | null format: int64

**schema_tokens**

Optional token count attributed to field specifications.

integer | null format: int64

**state_tokens**

Optional token count attributed to input state text.

integer | null format: int64

### Example

```json
{
  "answers": {
    "additionalProperty": {
      "source": "text",
      "type": "text"
    }
  }
}
```

400Invalid or unsupported extraction request

### 400

Invalid or unsupported extraction request

403Organization adoption and model management permission required

### 403

Organization adoption and model management permission required

404Model not found

### 404

Model not found

413Request body exceeds 8 MiB

### 413

Request body exceeds 8 MiB

502Extraction provider failed

### 502

Extraction provider failed

504Extraction timed out

### 504

Extraction timed out

FetchcURL

Request

```js
const url = 'https://app.everruns.com/api/v1/extractions';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"input":{"assets":{"additionalProperty":{"data_base64":"example","format":"png","type":"image"}},"fields":{"additionalProperty":{"decimals":1,"horizon":1,"instructions":"example","integer":true,"interval":"step","items":"text","max":1,"min":1,"null_threshold":1,"scale":"linear","step":"month","type":"text","unit":"example"}},"model":"example","provider":"example","provider_options":{"additionalProperty":"example"},"reference_date":"example","session_id":"example","state":"example","trace":"example","user":"example"},"model_id":"example"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

Request

```sh
curl --request POST \
  --url https://app.everruns.com/api/v1/extractions \
  --header 'Content-Type: application/json' \
  --data '{ "input": { "assets": { "additionalProperty": { "data_base64": "example", "format": "png", "type": "image" } }, "fields": { "additionalProperty": { "decimals": 1, "horizon": 1, "instructions": "example", "integer": true, "interval": "step", "items": "text", "max": 1, "min": 1, "null_threshold": 1, "scale": "linear", "step": "month", "type": "text", "unit": "example" } }, "model": "example", "provider": "example", "provider_options": { "additionalProperty": "example" }, "reference_date": "example", "session_id": "example", "state": "example", "trace": "example", "user": "example" }, "model_id": "example" }'
```

Additional language examples require JavaScript. The default request example is available above.

200400403404413502504

200 · Typed extraction values, evidence and usage

```json
{
  "answers": {},
  "model": "string"
}
```

400 · Invalid or unsupported extraction request

No response body example is declared for this status.

403 · Organization adoption and model management permission required

No response body example is declared for this status.

404 · Model not found

No response body example is declared for this status.

413 · Request body exceeds 8 MiB

No response body example is declared for this status.

502 · Extraction provider failed

No response body example is declared for this status.

504 · Extraction timed out

No response body example is declared for this status.

## Matching endpoints