webskillet 0.1.1

Python SDK for the Webskillet runs API

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.