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

fromwebskillet_clientimportWebskilletClientwithWebskilletClient(api_key="your-webskillet-api-key") asclient:
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:

fromwebskillet_clientimportAsyncWebskilletClientasyncwithAsyncWebskilletClient(api_key="your-webskillet-api-key") asclient:
result=awaitclient.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:

fromwebskillet_clientimport (
AuthenticationError, # 401/403 — missing or invalid API keyNotFoundError, # 404ValidationError, # other 4xxServerError, # 5xxNetworkError, # connection, DNS, TLS, or timeout failuresRunFailedError, # run completed with outcome="failed"
)
try:
result=client.runs.run(body={"task": "Extract the page title"})
exceptRunFailedErrorase:
print(f"Run {e.run_id} failed: {e.error}")
exceptAuthenticationError:
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", # defaulttimeout=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.