Extraction Actions - Optexity Documentation

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
`two_fa_action`	Wait for and extract 2FA code	2FA codes

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 values as variables
`llm_model_name`	`str`	`"gemini-2.5-flash"`	LLM model to use

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`	Required	Variable name to store the extracted text
`extraction_format`	`dict`	Required	Must contain `output_variable_name` as a key
`extraction_instructions`	`str \| None`	`None`	LLM fallback instructions if the locator fails
`llm_provider`	`"gemini"`	`"gemini"`	LLM provider to use for fallback
`llm_model_name`	`str`	`"gemini-2.5-flash"`	LLM model for fallback

extraction_format must contain output_variable_name as a key, or validation will fail.

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

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`

​Extraction Types

​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

​Two-Factor Authentication Extraction

​Properties

​Action Types

​Timing

​When to Use Each Type

Extraction Types

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

Two-Factor Authentication Extraction

Properties

Action Types

Timing

When to Use Each Type