Figranium Python SDK Quickstart

The Figranium Python SDK lets you drive a Figranium server from Python: build tasks with typed action helpers, run them synchronously or asynchronously, and stream results. This quickstart walks you from an empty project to running your first task in a handful of lines.

Prerequisites

Python 3.9 or later
A running Figranium instance (http://localhost:11345 by default)
An API key generated from the Figranium web UI

Install the SDK

pip install figranium-sdk

The package installs figranium (the import name) plus its only runtime dependency, httpx. See Installation for optional extras.

Create a client

Store your API key in an environment variable so it never lands in source control.

quickstart.py

import os
from figranium import Figranium

client = Figranium(
    base_url="http://localhost:11345",
    api_key=os.environ["FIGRANIUM_API_KEY"],
)

See Client configuration for every constructor option and Authentication for API key setup.

Define and save a task

Use actions helpers to describe the browser workflow. variable("query") produces the template token {$query} that is replaced at runtime.

quickstart.py

from figranium import Task, actions, variable

task: Task = {
    "name": "Search example",
    "url": "https://example.com",
    "mode": "scrape",
    "variables": {
        "query": {"type": "string", "value": "figranium"},
    },
    "actions": [
        actions.type("#search", variable("query")),
        actions.click("button[type=submit]"),
        actions.wait_for(".results"),
        actions.get_content(".results", var_name="html"),
    ],
}

saved = client.tasks.save(task)

See Actions for every helper and Variables for typed variable declarations.

Run the task

Use run_task (a shortcut for client.tasks.run) and pass runtime variable overrides in input.

quickstart.py

result = client.run_task(saved["id"], {"variables": {"query": "browser automation"}})

print(result["success"], result["outcome"])
print(result["data"])

Handle errors

Every HTTP, transport, and timeout failure raises FigraniumError. Inspect code and status to branch on the failure kind.

quickstart.py

from figranium import FigraniumError

try:
    result = client.run_task(saved["id"], {"variables": {"query": "..."}})
except FigraniumError as error:
    print(error.status, error.code, error.request_id)
    raise

See Errors for the full list of codes.

Complete example

quickstart.py

import os
from figranium import Figranium, FigraniumError, Task, actions, variable

client = Figranium(
    base_url="http://localhost:11345",
    api_key=os.environ["FIGRANIUM_API_KEY"],
)

task: Task = {
    "name": "Search example",
    "url": "https://example.com",
    "mode": "scrape",
    "variables": {
        "query": {"type": "string", "value": "figranium"},
    },
    "actions": [
        actions.type("#search", variable("query")),
        actions.click("button[type=submit]"),
        actions.wait_for(".results"),
        actions.get_content(".results", var_name="html"),
    ],
}

try:
    saved = client.tasks.save(task)
    result = client.run_task(saved["id"], {"variables": {"query": "browser automation"}})
    print(result["data"])
except FigraniumError as error:
    print(f"[{error.status}] {error.code}: {error}")
    raise
finally:
    client.close()

Direct execution without saving

For one-off runs, skip tasks.save and call client.scrape, client.agent, or client.headful directly. These use the same Task shape, but the server does not persist them.

direct_scrape.py

result = client.scrape({
    "url": "https://example.com",
    "selector": "body",
})
print(result["data"])

Next steps

Action helpers

Every helper you can use to build a task, from navigation to CAPTCHA solving.

Streaming

Iterate over live executions with client.executions.stream().

Handle errors

FigraniumError fields, codes, and cancellation semantics.

Tasks resource

Save, version, list, and run tasks programmatically.

JavaScript SDK

Python SDK

Swift SDK

Figranium Python SDK Quickstart

Prerequisites

Complete example

Direct execution without saving

Next steps

Action helpers

Streaming

Handle errors

Tasks resource

​Prerequisites

​Complete example

​Direct execution without saving

​Next steps

Action helpers

Streaming

Handle errors

Tasks resource

Prerequisites

Complete example

Direct execution without saving

Next steps