Extraction Actions

Extraction actions capture data from web pages during automation—essential for scraping, validation, and feeding dynamic values into subsequent actions.

Extraction Types

Type	Purpose	Best For
`llm`	AI-powered structured data extraction	Tables, forms, text content
`locator`	Extract text directly via Playwright locator	Single values, fast extraction, no LLM tokens
`network_call`	Capture API/AJAX responses	API data, JSON responses
`api_call`	Call an external REST API directly	Webhooks, triggering jobs, polling for async results
`screenshot`	Save visual snapshot	Receipts, proofs, visual records
`state`	Capture page state (URL, title, storage, cookies)	Debugging auth, navigation validation
`python_script`	Run custom Python code to extract data	Complex parsing, computed values
`two_fa_action`	Wait for and extract 2FA code	2FA codes

Common Properties

These properties sit on the extraction_action object itself, regardless of extraction type:

Property	Type	Default	Description
`allow_none`	`bool`	`false`	Allow `output_variable_names` to resolve to `null` without failing the workflow

`allow_none`

By default, if you declare output_variable_names and any of those variables comes back null, the workflow fails immediately with an error like:

Extraction produced null value(s) in variable 'price' and allow_none is False: [None]

Set allow_none: true on the extraction_action when the value may legitimately be absent on some pages:

{
  "type": "action_node",
  "extraction_action": {
    "allow_none": true,
    "llm": {
      "source": ["axtree"],
      "extraction_format": {
        "product_name": "str",
        "price": "str",
        "availability": "str"
      },
      "extraction_instructions": "Extract product details from the product page. Return null for any field not visible on the page.",
      "output_variable_names": ["price"]
    }
  }
}

Only use output_variable_names when you need to reference the extracted value in a later action (e.g. {price[0]}). If you only need the value in the output data and won’t reference it downstream, omit output_variable_names entirely — the null-check is skipped and the value is simply stored in OutputData.

LLM Extraction

The most powerful extraction method. Uses AI to parse page content into structured data.

{
  "extraction_action": {
    "llm": {
      "source": ["axtree"],
      "extraction_format": {
        "product_name": "str",
        "price": "str",
        "availability": "str"
      },
      "extraction_instructions": "Extract product details from the product page"
    }
  }
}

Properties

Property	Type	Default	Description
`source`	`list["axtree" \| "screenshot"]`	`["axtree"]`	Data sources to analyze
`extraction_format`	`dict`	Required	Expected output structure
`extraction_instructions`	`str`	Required	What to extract
`output_variable_names`	`list[str]`	`None`	Store specific keys as workflow variables for use in later actions. Only set this when you need to reference the value downstream. Null values fail the workflow unless `allow_none: true` is set.
`include_full_page`	`bool`	`false`	Capture the full scrollable page (not just the visible viewport) when `source` includes `"screenshot"`
`llm_model_name`	`str \| None`	`None`	LiteLLM model string, e.g. `"gemini/gemini-2.5-pro"`. Falls back to the task model, then `LLM_MODEL`. See Model Configuration

Source Selection

Source	Best For
`["axtree"]`	Text, tables, forms (default, fastest)
`["screenshot"]`	Charts, images, visual layouts
`["axtree", "screenshot"]`	Complex pages needing both

Extraction Format

Define output structure with type hints:

{
  "extraction_format": {
    "title": "str",
    "items": "List[str]",
    "count": "str"
  }
}

Only str and List[str] are supported types.

Storing as Variables

Use output_variable_names to make extracted values available for subsequent actions:

{
  "extraction_action": {
    "llm": {
      "extraction_format": {
        "order_ids": "List[str]",
        "total": "str"
      },
      "extraction_instructions": "Extract order IDs from the table",
      "output_variable_names": ["order_ids"]
    }
  }
}

After this action, use {order_ids[0]}, {order_ids[index]}, or iterate with for_loop_node.

Writing Good Instructions

Good examples:

{"extraction_instructions": "Extract all authorization numbers from the Auth Nbr column in the Authorizations table"}

{"extraction_instructions": "From the patient info section, extract: name (shown as 'Name:'), DOB, and member ID"}

Poor examples:

{"extraction_instructions": "Get the data"}

{"extraction_instructions": "Extract the numbers"}

Be specific about where data appears, what it looks like, and expected format.

Locator Extraction

Extract text from a specific element on the page using a Playwright locator — no LLM tokens consumed. If the locator fails, it can fall back to LLM extraction.

{
  "extraction_action": {
    "locator": {
      "command": "get_by_role(\"cell\", name=\"Authorization Number\").locator(\"+ td\")",
      "output_variable_name": "auth_number",
      "extraction_format": {
        "auth_number": "str"
      }
    }
  }
}

Properties

Property	Type	Default	Description
`command`	`str`	Required	Playwright locator command to find the element
`output_variable_name`	`str \| None`	`None`	Variable name to store the extracted text. When omitted, the value is stored under an auto-generated key (`node{index}_output`) and `extraction_format` must contain exactly one field. Accepts loop placeholders (e.g. `"patient_{row}"`) to store one value per iteration — see For Loop Node
`extraction_format`	`dict`	Required	Must contain `output_variable_name` as a key (or exactly one field when `output_variable_name` is omitted). Templated keys are expanded alongside `output_variable_name`
`extraction_instructions`	`str \| None`	`None`	LLM fallback instructions if the locator fails
`llm_model_name`	`str \| None`	`None`	LiteLLM model string used for the fallback, e.g. `"gemini/gemini-2.5-pro"`. Falls back to the task model, then `LLM_MODEL`
`llm_provider`	`str \| None`	`None`	Deprecated — prefix the provider in `llm_model_name` instead

Fallback Behavior

If the locator fails to find the element or find text content, two outcomes are possible:

With extraction_instructions — falls back to LLM extraction automatically
Without extraction_instructions — variable is set to None

{
  "extraction_action": {
    "locator": {
      "command": "get_by_label(\"Total Amount\")",
      "output_variable_name": "total_amount",
      "extraction_format": {
        "total_amount": "str"
      },
      "extraction_instructions": "Extract the total amount shown on the invoice page"
    }
  }
}

When to Use Locator vs LLM

Situation	Use
Element has a stable, reliable locator	`locator` (faster, no cost)
Page structure changes often	`llm`
Single known value to extract	`locator` with LLM fallback
Multiple fields at once	`llm`

Always provide extraction_instructions as a fallback. This makes the extraction resilient if the page structure changes.

Network Call Extraction

Capture data from API requests and responses:

{
  "extraction_action": {
    "network_call": {
      "url_pattern": "https://inference-api.optexity.com/orders"
    }
  }
}

Properties

Property	Type	Default	Description
`url_pattern`	`str \| None`	`None`	URL substring to match
`extract_from`	`"request" \| "response"`	`None`	Extract from request or response
`download_from`	`"request" \| "response"`	`None`	Download as file
`download_filename`	`str \| None`	Auto-generated	Filename for download

Use network_call to intercept requests the page already makes. Use api_call (below) to initiate your own HTTP request to any external endpoint.

API Call Extraction

Make an outbound REST API call directly from the automation—useful for hitting webhooks, triggering backend jobs, enriching data from a third-party service, or polling an async endpoint until it’s ready. The full response is stored as a variable for use in later actions.

{
  "extraction_action": {
    "api_call": {
      "url": "https://inference-api.optexity.com/v1/orders",
      "method": "GET"
    }
  }
}

Properties

Property	Type	Default	Description
`url`	`str`	Required	Endpoint to call
`method`	`"GET" \| "POST" \| "PUT" \| "PATCH" \| "DELETE"`	`"GET"`	HTTP method
`headers`	`dict[str, str]`	`{}`	Request headers
`body`	`dict \| str \| None`	`None`	Request body. A `dict` is sent as JSON; a `str` is sent as raw content
`query_params`	`dict[str, str]`	`{}`	URL query parameters
`output_variable_names`	`list[str]`	`["api_result"]`	Variable name(s) to store the response under
`timeout`	`float`	`30.0`	Request timeout in seconds
`poll_condition`	`str \| None`	`None`	Expression to re-poll until satisfied (see Polling)
`poll_interval`	`float`	`5.0`	Seconds to wait between poll attempts
`max_poll_attempts`	`int`	`10`	Maximum number of poll attempts

Response Shape

The stored variable holds a dict with the following keys:

Key	Type	Description
`status_code`	`int \| null`	HTTP status code (`null` on a connection error or timeout)
`headers`	`dict[str, str]`	Response headers
`body`	`any`	Parsed JSON if the response is JSON, otherwise the raw text
`error`	`str`	Present only on failure—`"timeout"` or `"http_error"`

Using the Response

Reference fields of the response in later actions with dot-path syntax: {var.field}, {var.nested.field}, and {var.array[0].field}. Both object keys and array indices are supported.

{
  "extraction_action": {
    "api_call": {
      "url": "https://inference-api.optexity.com/v1/customers",
      "method": "POST",
      "headers": { "Authorization": "Bearer {api_token}" },
      "body": { "email": "{customer_email}" },
      "output_variable_names": ["create_result"]
    }
  }
}

After this action, {create_result.body.id} resolves to the new customer’s ID, and {create_result.status_code} resolves to 201.

Dot-path resolution ({var.field}) applies only to dict-valued variables such as API responses. The existing list-indexing format {var[0]} from llm extraction is unaffected.

Polling

For asynchronous endpoints, set poll_condition to keep re-requesting until the condition is met (or max_poll_attempts is reached). The condition is a Python-style boolean expression evaluated against the response dict, supporting both top-level keys and dot-paths:

{
  "extraction_action": {
    "api_call": {
      "url": "https://inference-api.optexity.com/v1/jobs/{job_id}",
      "poll_condition": "body.status == 'completed'",
      "poll_interval": 10.0,
      "max_poll_attempts": 30
    }
  }
}

Example conditions:

Condition	Meaning
`status_code == 200`	Stop once the request returns HTTP 200
`body.status == 'completed'`	Stop once the response body’s `status` field is `"completed"`
`body.progress >= 100`	Stop once `progress` reaches 100

If the condition is never met within max_poll_attempts, the last response is stored and the automation continues.

Screenshot Extraction

Save a screenshot for later analysis:

{
  "extraction_action": {
    "screenshot": {
      "filename": "confirmation.png",
      "full_page": true
    }
  }
}

Property	Type	Default	Description
`filename`	`str`	Required	Output filename
`full_page`	`bool`	`True`	Entire page or viewport only

State Extraction

Capture page state, including URL/title plus browser storage and cookies:

{
  "extraction_action": {
    "state": {}
  }
}

Output

state extraction appends an OutputData.json_data object with the following shape:

Key	Type	Description
`page_url`	`str`	Current page URL
`page_title`	`str`	Current page title
`local_storage`	`dict[str, str \| null]`	All `localStorage` key/value pairs
`session_storage`	`dict[str, str \| null]`	All `sessionStorage` key/value pairs
`cookies`	`list[dict]`	Cookies from the current browser context
`document_cookie`	`str`	`document.cookie` string for the current page

Python Script Extraction

Run a custom Python function to extract data from the current page’s accessibility tree or perform any computed logic.

{
  "extraction_action": {
    "python_script": {
      "script": "async def code_fn(axtree, browser):\n    rows = [r.strip() for r in axtree.split('\\n') if r.strip()]\n    return {'row_count': str(len(rows))}",
      "extraction_format": {
        "row_count": "str"
      },
      "output_variable_names": ["row_count"]
    }
  }
}

Properties

Property	Type	Default	Description
`script`	`str`	Required	Python source defining an `async def code_fn(axtree, browser)` function. Must return a `dict` matching `extraction_format`, or `None`.
`extraction_format`	`dict \| None`	`None`	Expected output structure (same `str` / `List[str]` types as `llm` extraction)
`output_variable_names`	`list[str] \| None`	`None`	Keys from the returned dict to store as workflow variables

The code_fn function receives the page’s accessibility tree as a plain string (axtree) and the Playwright browser object. Return None to skip storing any output.

Two-Factor Authentication Extraction

Wait for and extract 2FA code:

{
  "extraction_action": {
    "two_fa_action": {
      "action": "email_two_fa_action",
      "output_variable_name": "two_fa_code"
    }
  }
}

Properties

Property	Type	Default	Description
`action`	`"email_two_fa_action" \| "slack_two_fa_action" \| "sms_two_fa_action"`	Required	The type of 2FA action to use
`output_variable_name`	`str`	Required	The name of the variable to store the 2FA code in
`instructions`	`str`	`None`	Optional Custom instructions for code extraction
`max_wait_time`	`float`	`300.0`	The maximum time to wait for the 2FA code
`check_interval`	`float`	`10.0`	The interval to check for the 2FA code

Action Types

Action Type	Description
`email_two_fa_action`	Wait for and extract 2FA code from email
`slack_two_fa_action`	Wait for and extract 2FA code from Slack
`sms_two_fa_action`	Wait for and extract 2FA code from SMS via Twilio

For more information on how to use the 2FA code in your automation, please refer to the Two-Factor Authentication Integration documentation.

Timing

Extraction actions have different timing defaults to allow pages to fully load:

Property	Default for Extractions
`before_sleep_time`	`3.0` seconds
`end_sleep_time`	`0.0` seconds

Override if needed:

{
  "type": "action_node",
  "extraction_action": {
    "llm": { ... }
  },
  "before_sleep_time": 5.0
}

When to Use Each Type

Scenario	Recommended
Extract text/tables from page	`llm` with `axtree`
Extract a single known element	`locator`
Extract with locator + LLM fallback	`locator` with `extraction_instructions`
Charts, images, visual content	`llm` with `screenshot`
Intercept API data the page requests	`network_call`
Call an external API / webhook directly	`api_call`
Poll an async endpoint until ready	`api_call` with `poll_condition`
Visual proof/documentation	`screenshot`
Validate navigation	`state`
Complex parsing / computed values	`python_script`
Value may be null on some pages	Any type + `allow_none: true` on `extraction_action`

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Extraction Types

Common Properties

`allow_none`

LLM Extraction

Properties

Source Selection

Extraction Format

Storing as Variables

Writing Good Instructions

Locator Extraction

Properties

Fallback Behavior

When to Use Locator vs LLM

Network Call Extraction

Properties

API Call Extraction

Properties

Response Shape

Using the Response

Polling

Screenshot Extraction

State Extraction

Output

Python Script Extraction

Properties

Two-Factor Authentication Extraction

Properties

Action Types

Timing

When to Use Each Type

​Extraction Types

​Common Properties

​allow_none

​LLM Extraction

​Properties

​Source Selection

​Extraction Format

​Storing as Variables

​Writing Good Instructions

​Locator Extraction

​Properties

​Fallback Behavior

​When to Use Locator vs LLM

​Network Call Extraction

​Properties

​API Call Extraction

​Properties

​Response Shape

​Using the Response

​Polling

​Screenshot Extraction

​State Extraction

​Output

​Python Script Extraction

​Properties

​Two-Factor Authentication Extraction

​Properties

​Action Types

​Timing

​When to Use Each Type

Extraction Types

Common Properties

`allow_none`

LLM Extraction

Properties

Source Selection

Extraction Format

Storing as Variables

Writing Good Instructions

Locator Extraction

Properties

Fallback Behavior

When to Use Locator vs LLM

Network Call Extraction

Properties

API Call Extraction

Properties

Response Shape

Using the Response

Polling

Screenshot Extraction

State Extraction

Output

Python Script Extraction

Properties

Two-Factor Authentication Extraction

Properties

Action Types

Timing

When to Use Each Type