Downloads & Files

Optexity can download files from websites and upload files to forms.

Download Methods

Method	Trigger
Click download link	`click_element` with `expect_download=true`
Select export option	`select_option` with `expect_download=true`
Save page as PDF	`download_url_as_pdf`
Save bytes from a script	`ctx.save_download()` in a `python_script`

Click to Download

{
  "interaction_action": {
    "click_element": {
      "command": "get_by_role(\"button\", name=\"Download Report\")",
      "expect_download": true,
      "download_filename": "monthly_report.pdf"
    }
  }
}

Property	Type	Default	Description
`expect_download`	`bool`	`False`	Action triggers download
`download_filename`	`str \| None`	Auto-generated UUID	Filename for download
`download_metadata`	`dict \| None`	`None`	Freeform JSON stored with the download

Download Metadata

Attach freeform JSON to a download when using expect_download. Values support the same {variable} substitution as other action fields:

{
  "interaction_action": {
    "click_element": {
      "command": "get_by_text(\"{doc_ids[index]}\")",
      "expect_download": true,
      "download_filename": "doc_{doc_ids[index]}.pdf",
      "download_metadata": {
        "doc_id": "{doc_ids[index]}",
        "source": "ehr",
        "kind": "report"
      }
    }
  }
}

Metadata is keyed by the final filename and returned on callbacks as optional downloads_with_metadata (see Callbacks). On interaction actions, only click_element / select_option with expect_download support this field; from a Python script, pass metadata= to ctx.save_download().

Save a File from a Python Script

When a script has already fetched or assembled the bytes — an API response, a CSV it built, pages it reassembled into a PDF — it can register the file directly instead of routing it back through the browser:

{
  "type": "action_node",
  "extraction_action": {
    "python_script": {
      "script": "async def code_fn(axtree, browser, ctx):\n    page = await ctx.get_page()\n    csv = await page.evaluate(\"() => fetch('/export.csv').then(r => r.text())\")\n    await ctx.save_download('export_{index}.csv', csv, metadata={'kind': 'export'})\n    return {\"saved\": 1}",
      "output_variable_names": ["saved"],
      "extraction_format": {"saved": "int"}
    }
  }
}

The file is uploaded and its metadata persisted exactly as for expect_download downloads. This replaces the older workaround of base64-ing bytes into a Blob, injecting an <a download> anchor, and adding a second click_element node to click it — which cost a screenshot, an axtree capture and a trajectory upload per file. See Python Script Action for the full ctx reference.

Select to Download

{
  "interaction_action": {
    "select_option": {
      "command": "get_by_label(\"Export Format\")",
      "select_values": ["CSV"],
      "expect_download": true,
      "download_filename": "data.csv"
    }
  }
}

Save Page as PDF

Capture current page or specific URL as PDF:

{
  "interaction_action": {
    "download_url_as_pdf": {
      "download_filename": "page_snapshot.pdf"
    }
  }
}

Multiple Downloads

Use for_loop_node to download multiple files:

{
  "type": "for_loop_node",
  "variable_name": "doc_ids",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "get_by_text(\"{doc_ids[index]}\")",
        "expect_download": true,
        "download_filename": "doc_{doc_ids[index]}.pdf"
      }
    }
  }]
}

Use variable substitution in download_filename to create unique filenames.

When the download links are on the page but their identifiers aren’t known in advance, iterate a locator instead of a variable and use the loop index for the filename:

{
  "type": "for_loop_node",
  "locator": "locator(\"tr.invoiceRow\")",
  "index_variable_name": "row",
  "nodes": [{
    "type": "action_node",
    "interaction_action": {
      "click_element": {
        "command": "{locator[row]}.get_by_role(\"link\", name=\"Download\")",
        "expect_download": true,
        "download_filename": "invoice_{row}.pdf"
      }
    }
  }]
}

See For Loop Node for the locator loop’s placeholders and timing.

Upload Files

The file source must be exactly one of file_path or file_url. Setting both, or neither, is rejected by the schema. Upload from a local path:

{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_path": "/path/to/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}

Upload from a public URL (downloaded to a temp file just before upload, then cleaned up):

{
  "interaction_action": {
    "upload_file": {
      "command": "get_by_label(\"Upload Document\")",
      "file_url": "https://example.com/files/document.pdf",
      "prompt_instructions": "Upload the document"
    }
  }
}

Property	Description
`command` / `xpath`	Locator for file input
`file_path`	Absolute or relative local path (supports variables)
`file_url`	Public `http://` or `https://` URL (supports variables). 120s download timeout. The automation fails if the download errors or returns a non-2xx status. The file extension is derived from the URL path, `Content-Disposition`, or `Content-Type` (in that order) so file inputs that check extensions still validate.

Download Storage

Downloaded files are stored in the task’s downloads directory:

/tmp/optexity/{task_id}/downloads/
├── monthly_report.pdf
├── data.csv
└── doc_123.pdf

Waiting for Downloads

Optexity automatically waits for downloads when expect_download=true. For large files, increase timing:

{
  "type": "action_node",
  "interaction_action": {
    "click_element": {
      "command": "get_by_text(\"Download Large File\")",
      "expect_download": true
    }
  },
  "end_sleep_time": 10.0
}

Failure on Missing Download

When a node expects a file but none is produced, the task fails rather than silently continuing. This applies to both download mechanisms: expect_download=true (click_element / select_option):

Condition	Task error
No file appears within the download timeout	`could not download file when expect download is true`
A file appears but is empty or missing after being saved	`file appeared but was empty/missing after move`

download_url_as_pdf:

Condition	Task error
No URL could be resolved for the page	`could not download file for download_url_as_pdf: no URL found`
The request returns a non-OK HTTP status	`could not download file for download_url_as_pdf: HTTP <status>`
The saved PDF is empty or missing	`file appeared but was empty/missing after move`

If a download is slow, increase end_sleep_time (see below) so the file has time to finish before the timeout triggers a failure.

Best Practices

Practice	Recommendation
Set `expect_download`	Always when download is expected
Use descriptive filenames	Include IDs or dates
Handle large files	Increase `end_sleep_time`
Validate upload paths	Ensure absolute paths are accessible

Quickstart

Building Automations

Action Types

Inference

Advanced

FAQs

Download Methods

Click to Download

Download Metadata

Save a File from a Python Script

Select to Download

Save Page as PDF

Multiple Downloads

Upload Files

Download Storage

Waiting for Downloads

Failure on Missing Download

Best Practices

​Download Methods

​Click to Download

​Download Metadata

​Save a File from a Python Script

​Select to Download

​Save Page as PDF

​Multiple Downloads

​Upload Files

​Download Storage

​Waiting for Downloads

​Failure on Missing Download

​Best Practices

Download Methods

Click to Download

Download Metadata

Save a File from a Python Script

Select to Download

Save Page as PDF

Multiple Downloads

Upload Files

Download Storage

Waiting for Downloads

Failure on Missing Download

Best Practices