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.

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

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.1
File Size Uploaded Provenance Actions
figranium_sdk-0.1.1.tar.gz 41.0 kB With provenance Details for figranium_sdk-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 64.3 kB

Release files / figranium_sdk-0.1.1.tar.gz

Download URL figranium_sdk-0.1.1.tar.gz
Size 41.0 kB
Tags Source
SHA-256 checksum
How to use checksums
e050d7d3abdf48295b6d5b2970a9fd91ec762175013e39f5c860d347b96a1c3b
BLAKE2b-256 checksum
How to use checksums
47cba7ad0e43b2895e91b185ddae894b683a264333705b0d74c4ac6f0c79d01c
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 Sep 26, 2026.

Transparency log

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

Download URL figranium_sdk-0.1.1-py3-none-any.whl
Size 23.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
aabb7fd0363df02829037c48d70a07fed675bb75a99435334b195a1384b9b125
BLAKE2b-256 checksum
How to use checksums
7740f7de394679fdf02e49a3bdb4a7181ffec3f4ab03d4ecadb18a5b87eb546c
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 Sep 26, 2026.

Transparency log

Security for figranium-sdk 0.1.1

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.1.1.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 Sep 26, 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