Skip to main content
Figranium Banner

Figranium Python SDK

PyPI version

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

Documentation

  • 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.

License

Apache-2.0

Metadata

Release files for figranium-sdk 0.2.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.2.0
File Size Uploaded Provenance Actions
figranium_sdk-0.2.0.tar.gz 41.7 kB With provenance Details for figranium_sdk-0.2.0.tar.gz

Built distribution (wheel)

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

Total release size: 65.8 kB

Release files / figranium_sdk-0.2.0.tar.gz

Download URL figranium_sdk-0.2.0.tar.gz
Size 41.7 kB
Tags Source
SHA-256 checksum
How to use checksums
95959a00f68f70c0181751cc207f2273b855f62fb454f7f066af096e26281b31
BLAKE2b-256 checksum
How to use checksums
e6e1d536af04286f8f7979d5211352cd63af1c475a4137efb62126bb3aa84d44
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

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

Download URL figranium_sdk-0.2.0-py3-none-any.whl
Size 24.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ffd23ba8b221eec551c04edbe726ff7af31b1d5e98f0d1d6ba748160c2fd1d49
BLAKE2b-256 checksum
How to use checksums
0ea9210f68e9fe0ed3852d1a002eaea6cf0f01dffe4267cc8c8c9977644546ed
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

Security for figranium-sdk 0.2.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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for figranium_sdk-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 3, 2026.

Transparency log

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