webskillet

The official Python SDK for the Webskillet API. Run web tasks programmatically, poll for results, and manage skillets and auth sessions — with full type hints and Pydantic models throughout.

Installation

pip install webskillet

Requires Python 3.10+.

Quickstart

from webskillet_client import WebskilletClient

with WebskilletClient(api_key="your-webskillet-api-key") as client:
    result = client.runs.run(
        body={
            "task": "Extract the title of example.com",
            "startUrl": "https://example.com",
            "skilletId": "example-title",
        },
        timeout_seconds=600,
    )
    print(result.status, getattr(result, "result", None))

runs.run() starts a run and polls every five seconds until it is completed or canceled. It waits indefinitely by default; pass timeout_seconds to stop waiting after a fixed duration (raises TimeoutError). A run that completes with outcome="failed" raises RunFailedError.

Async usage

AsyncWebskilletClient exposes the same services with the same signatures:

from webskillet_client import AsyncWebskilletClient

async with AsyncWebskilletClient(api_key="your-webskillet-api-key") as client:
    result = await client.runs.run(body={"task": "Extract the page title"})

Managing runs manually

Skip runs.run() when you need custom polling or fire-and-forget behavior:

started = client.runs.start(body={"task": "Extract the page title"})
current = client.runs.get(run_id=started.id)
updated = client.runs.update(
    run_id=started.id,
    body={"title": "Example page title"},
)
recent = client.runs.list(limit=20)

Skillets and auth sessions

skillets = client.skillets.list()

sessions = client.auth_sessions.list()
session = client.auth_sessions.get(auth_session_id=sessions[0].id)
recording = client.auth_sessions.record(
    body={"name": "GitHub", "startUrl": "https://github.com/login"}
)

Error handling

All errors inherit from WebskilletError, so one except clause covers everything. Catch more specific types when you need to branch:

from webskillet_client import (
    AuthenticationError,  # 401/403 — missing or invalid API key
    NotFoundError,        # 404
    ValidationError,      # other 4xx
    ServerError,          # 5xx
    NetworkError,         # connection, DNS, TLS, or timeout failures
    RunFailedError,       # run completed with outcome="failed"
)

try:
    result = client.runs.run(body={"task": "Extract the page title"})
except RunFailedError as e:
    print(f"Run {e.run_id} failed: {e.error}")
except AuthenticationError:
    print("Check your API key")

API errors carry status_code and the response body; RunFailedError carries run_id and the run's error payload.

Configuration

client = WebskilletClient(
    api_key="your-webskillet-api-key",
    base_url="https://webskillet.ai",  # default
    timeout=30.0,                       # per-request timeout in seconds
)

Requests authenticate with the x-api-key header. You can also pass a preconfigured httpx.Client (or httpx.AsyncClient) via the client parameter for custom proxies, retries, or transports.