Extract typed fields (hosted ExtractionProvider)

curl -X POST https://api.runtype.com/v1/runtime/extractions \
     -H "Authorization: <apiKey>" \
     -H "Content-Type: application/json" \
     -d '{
  "fields": {},
  "state": "Invoice #INV-2024-0892 from Acme Supplies dated March 15, 2024. Total amount due: $4,750.00. Payment terms: Net 30. Line items: 10x Widget A @ $250.00, 5x Widget B @ $450.00."
}'

{
  "answers": {},
  "extraction": {
    "keySource": "user",
    "provider": "openai",
    "requestedModel": "runtype-extract-v2",
    "resolvedModelId": "gpt-4o-2024-08-06",
    "route": "hosted",
    "usage": {
      "inputTokens": 312,
      "outputTokens": 87,
      "reported": true,
      "passes": 1
    },
    "estimatedCostUsd": 0.0042
  },
  "model": "runtype-extract-v2",
  "truncated": false,
  "usage": {},
  "values": {},
  "stateText": "Invoice #INV-2024-0892 from Acme Supplies dated March 15, 2024. Total amount due: $4,750.00. Payment terms: Net 30. Line items: 10x Widget A @ $250.00, 5x Widget B @ $450.00."
}

The runtime-family extraction contract consumed by @runtypelabs/runtime’s HostedExtractionProvider, so a self-hosted runtime on platform or hybrid keys runs the extract step through Runtype with a Self-hosted Runtime key (RUNTIME:EXECUTE). Billed and recorded like an extract flow step. Requires an Enterprise plan: ineligible accounts receive 403 (code BYOC_PLAN_REQUIRED).

Authentication

AuthorizationBearer

API key or Clerk session token

Request

This endpoint expects an object.

fieldsmap from strings to anyRequired

Field name to field spec, each { type: "text" | "number" | "date" | "time" | "datetime" | "duration" | "list" | "estimate" | "forecast", instructions?, ... }. Refused with EXTRACTION_FIELDS_INVALID and one sentence per problem.

statestringRequired

The text to read. Never echoed in errors or logs.

executionIdstringOptional>=1 character

The self-hosted execution asking, recorded on the extraction telemetry.

imageslist of anyOptional

Up to the model limit of embedded images: data: URLs or { contentType, base64 }. Remote URLs are refused.

modelstringOptional>=1 character

Extraction model id; defaults to the platform default.

optionsobjectOptional

referenceDatestringOptional

ISO date anchoring dates written without a year.

stepIdstringOptional>=1 character

Response

The values, answers and extraction metadata

answersmap from strings to any

One answer per field: value, confidence, pNull, span(s) and estimate intervals.

extractionobject

modelstring

truncatedboolean

usagemap from strings to any

valuesmap from strings to any

One value per field; null when the input does not determine it.

stateTextstringOptional

The text answer spans index into; present only when options.returnStateText asked for it.

Errors

400

Bad Request Error

401

Unauthorized Error

402

Payment Required Error

403

Forbidden Error

422

Unprocessable Entity Error

429

Too Many Requests Error

500

Internal Server Error