Skip to main content
Figranium Banner

Figranium Python SDK

Official Python SDK for Figranium, the self-hosted browser automation and web scraping platform.

  • Synchronous and asynchronous clients
  • Type hints and a py.typed marker
  • API-key and persistent browser-session authentication
  • Configurable timeouts, custom httpx clients, structured errors, and SSE streams
  • Python 3.9+

Install

pip install figranium-sdk

Quick start

import os

from figranium import Figranium

with Figranium(
    base_url="http://localhost:11345",
    api_key=os.environ["FIGRANIUM_API_KEY"],
) as figranium:
    tasks = figranium.tasks.list_summaries()["tasks"]
    result = figranium.run_task(
        tasks[0]["id"],
        {
            "variables": {"query": "Python SDK"},
        },
    )

print(result.get("data"))
print(result.get("outcome"))  # success | error | stopped | crashed | anti_bot

base_url defaults to http://localhost:11345. API keys use Authorization: Bearer by default. Set api_key_header="x-api-key" if your deployment expects that header.

Create a typed task

from figranium import Figranium, Task, actions, variable

task: Task = {
    "name": "Search and extract",
    "description": "Runs a search and captures visible results",
    "url": "https://example.com",
    "mode": "agent",
    "variables": {"query": {"type": "string", "value": "figranium"}},
    "actions": [
        actions.wait_for("#search"),
        actions.type("#search", variable("query")),
        actions.press("Enter", "#search"),
        actions.wait_for(".results"),
        actions.get_content(".results", "resultText"),
    ],
}

with Figranium(api_key="...") as client:
    saved = client.tasks.save(task)
    result = client.run_task(
        saved["id"],
        {
            "variables": {"query": "browser automation"},
        },
    )

variable("query") produces Figranium's required {$query} syntax. Action helpers generate unique IDs and accept base={...} for common fields or a caller-supplied ID. Plain action dictionaries remain supported when every specification field is needed.

CAPTCHA-aware tasks can wait for a challenge and solve it separately:

actions.wait_for_captcha(
    captcha_type="turnstile",
    selector="#challenge",
    timeout=120_000,
    var_name="captchaReady",
)
actions.solve_captcha(captcha_type="turnstile", timeout=120_000)

Async client

Every resource is available through AsyncFigranium with the same method names:

from figranium import AsyncFigranium

async with AsyncFigranium(api_key="...") as client:
    result = await client.run_task("task-id", {"variables": {"query": "async Python"}})

Stream executions

Synchronous streams are ordinary iterators:

with Figranium(api_key="...") as client:
    for event in client.executions.stream():
        print(event.get("event"), event["data"])

Asynchronous streams are async iterators:

async with AsyncFigranium(api_key="...") as client:
    async for event in client.executions.stream():
        print(event.get("event"), event["data"])

Streams remain open unless the server closes them, iteration stops, or an optional stream timeout is supplied with options={"timeout": 60}.

Error handling

from figranium import FigraniumError

try:
    result = client.run_task("missing-task")
except FigraniumError as error:
    print(error.status)  # HTTP status, or 0 for transport failures
    print(error.code)  # e.g. TASK_NOT_FOUND
    print(error.details)  # server-provided diagnostics
    print(error.request_id)  # supplied by the server or proxy, when available

Every request accepts an options keyword containing headers and timeout. The client-wide timeout defaults to 30 seconds.

Session-only administration

Figranium's /api/settings/* endpoints require an authenticated session rather than an API key. Set session=True, log in through client.auth.login(...), and reuse the same client; httpx maintains its cookie jar automatically.

with Figranium(base_url="https://figranium.example", session=True) as admin:
    admin.auth.login("admin@example.com", "password")
    models = admin.settings.get_ai_models()

Custom HTTP clients

Supply an httpx.Client or httpx.AsyncClient to integrate custom transports, proxies, tracing, or test doubles. The SDK does not close a client supplied by the caller.

import httpx

http_client = httpx.Client(proxy="http://proxy.example:8080")
client = Figranium(api_key="...", http_client=http_client)

See docs/API.md for the full method index and examples for complete sync and async examples.

Compatibility

The initial Python release mirrors @figranium/sdk 0.2.0 and its Figranium API 0.14.4 compatibility target. Request payloads and responses remain dictionaries so newer servers can add fields without breaking SDK consumers.

License

Apache-2.0

Metadata

Release files for figranium-sdk 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for figranium-sdk 0.1.0
File Size Uploaded Provenance Actions
figranium_sdk-0.1.0.tar.gz 40.1 kB Without provenance Details for figranium_sdk-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for figranium-sdk 0.1.0
File Interpreter ABI Platform Actions
figranium_sdk-0.1.0-py3-none-any.whl Python 3 none any Details for figranium_sdk-0.1.0-py3-none-any.whl

Total release size: 63.3 kB

Release files / figranium_sdk-0.1.0.tar.gz

Download URL figranium_sdk-0.1.0.tar.gz
Size 40.1 kB
Tags Source
SHA-256 checksum
How to use checksums
db82a7bbb6f934496e26c10b309cb3234c4f90855267a25281fd6ab48adca9d2
BLAKE2b-256 checksum
How to use checksums
84617ec4fd38ee427a412e4888b4cc17d57e29233be20c46f7643420f05f0935
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Release files / figranium_sdk-0.1.0-py3-none-any.whl

Download URL figranium_sdk-0.1.0-py3-none-any.whl
Size 23.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f9ca25fde0e65626a0220e3c79efca9b50a5e99eaf50394f2c50944d7a681fb1
BLAKE2b-256 checksum
How to use checksums
1e4ade5bfed38b1d72fd3b537de6b39346042315994d04b8b83dc4bb80d189d0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.9.6

Security for figranium-sdk 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page