| I/O | | | | |
input | Input column name, column index, or list of columns supplied together as DATA for each row. If omitted, all dataframe columns are supplied. | array, null | null | No |
output | Desired extraction. Use an object keyed by output column name for structured fields, a string for one prompted value, or an array of field names/definitions. Each field may use the schema options below. | string, array, object, null | null | No |
| Options | | | | |
record_examples | Whole-record examples. Each example has a separate input value or record and the complete expected output record. Optional name and notes provide model-visible context. Use {name: ..., notes: ..., input: ..., output: ...}. Omitted nullable output fields are completed with null. Required non-null nested properties must be supplied. This differs from examples nested under one output field, which teach only that field. | array, object, null | null | No |
web_search | Enable OpenAI Responses web search; the model decides when searching helps. When true, every row also receives web_search_sources: a deduplicated list of {title, url} objects in source order, or an empty list when no source was used. This reserved column is automatic. Requires protocol responses. Defaults to false. | boolean | false | No |
instructions | Additional guidance applied to every input row. Use this for decision rules, evidence priorities, normalization requirements, or other behavior that applies to the complete extraction. | string, array, null | null | No |
| Formatting | | | | |
output_format | How extracted fields are written. columns writes one dataframe column per field (default); dictionary keeps one object; concatenate joins fields into one string using char. | string, null; one of:- dictionary
- columns
- concatenate
| null | No |
char | Separator used only when output_format is concatenate. Defaults to comma-space. | string | ", " | No |
| Execution | | | | |
threads | Maximum number of row-level requests sent in parallel. The configured default is 32. | integer | — | No |
timeout | Maximum seconds for one HTTP attempt. The configured default is 12; deadline can end the overall call sooner. | number | — | No |
deadline | Total seconds allowed for the entire wrangle call, including queued work, retries, and backoff. The configured default is 15. | number | — | No |
| Errors | | | | |
retries | Number of additional attempts after a retryable failure. The configured default is 1. Backoff and request timeouts remain bounded by deadline. | integer | — | No |
| Details | | | | |
api_key | OpenAI API key used for this wrangle, normally supplied through a recipe variable. | string | — | Yes |
model_id | ID of a saved extract.ai definition. Use it instead of defining an output schema. When output is also supplied with model_id in a recipe, output names the destination column or columns for the saved fields. | string, null | null | No |
model | OpenAI model ID for this call. If omitted, uses the configured extract.ai default; a saved model definition may supply its own model. | string | — | No |
url | Override the endpoint for the selected protocol. A chat/completions URL selects the legacy protocol only when protocol is omitted; new recipes should use the configured Responses endpoint. | string | — | No |
provider | AI service provider. Currently only OpenAI is supported. | string; one of: | — | No |
protocol | OpenAI API protocol. Responses is the configured default and is required for web_search; chat_completions remains available for legacy definitions. | string; one of:- responses
- chat_completions
| — | No |
store | Whether OpenAI may store Responses API results. Defaults to false. | boolean | — | No |
cache | Reuse identical successful results from the bounded warm-instance cache. Defaults to true. Set false when fresh model or web results are required. | boolean | — | No |
cache_ttl | Maximum age in seconds for a cached result used by this call. Applies to extracted values and web_search_sources together. | number | — | No |
strict | Require OpenAI structured-output strict mode. Defaults to true. Definitions with dynamic dictionary keys automatically switch to non-strict provider mode and are still validated locally. | boolean | — | No |
reasoning | Responses API reasoning controls. Set effort for reasoning-capable models. The configured default is none when that model supports it; otherwise the provider default applies. | object | — | No |
verbosity | Responses API text verbosity for compatible models. Defaults to low when supported; ignored with a warning for incompatible models. | string; one of: | — | No |
| Conditions | | | | |
if | Condition that determines whether the wrangle runs as a whole. Recipe variables may be referenced with ${variable}. | string | — | No |
where | Filter rows before applying the wrangle using SQL-like criteria, such as column1 = 123 OR column2 = 'abc'. | string | — | No |
where_params | Values used with where for parameterized criteria. Uses SQLite placeholder syntax such as ? or :name. | array, object | — | No |