Skip to main content
The Keenable Python SDK gives your code web search, page fetch and Monitors. This page covers version 0.2.0, the version in the SDK repository. The latest release on PyPI is 0.1.5 (checked 2026-11-19), so the parts marked with a newer “Needs SDK” version aren’t in the package you install yet. For the other languages, see TypeScript, Go and Rust. For what all four SDKs share, see SDKs.

Install

Install the package. The SDK needs Python 3.9 or newer:
The package depends on httpx and httpcore. On macOS and many Linux distributions, system Python refuses a global pip install. If it does, run python3 -m venv .venv and source .venv/bin/activate first. To see which version you have, run pip show keenable.

Authenticate

Search and fetch work without an API key. An API key raises your rate limit, and Monitors needs one. Set KEENABLE_API_KEY and create the client with Keenable(), which reads the variable. To pass the key in code, use Keenable(api_key=...). If you pass no api_key and KEENABLE_API_KEY is unset, the client calls the keyless endpoints. The constructor takes these settings: Every call also takes timeout, max_retries and extra_headers as keyword arguments. They override the client’s settings for that call. This program runs one keyless search and prints the top 3 results as a citable block:
main.py
Save it as main.py and run python main.py. You see one [n] Title (url) header per result, followed by the page text. Search filters are keyword arguments: exclude_domains, published_after, published_before, acquired_after, acquired_before, snippet_max_length, max_results, query_time, objective, disable_cards, site and mode. Each one is described under Search parameters. To change how much text the citable block holds, see Context size. Needs SDK 0.2.0 or later: objective.

Fetch

This program fetches one page without a key and prints its title and the first 300 characters of its markdown:
main.py
Pass the fetch options as keyword arguments: fetch(url, max_chars=..., live=..., prompt=...). Each one is described under Fetch parameters.

Monitors

Needs SDK 0.2.0 or later. The latest release on PyPI is 0.1.5. Until a newer release is out, call the Monitors API over HTTP. A monitor watches the web for a topic and keeps every new page that matches. The Monitors API is under client.monitors. It needs an API key: without one, a call fails with the SDK’s authentication error and sends no request. This program creates a monitor with a webhook, then prints its ID, status and webhook signing secret:
main.py
Set KEENABLE_API_KEY before you run it. Keep the secret: the API returns it only here and in an update that adds the first webhook, and you need it to verify each delivery. Store it where your webhook handler can read it, and keep it out of logs. AsyncKeenable().monitors has the same methods, and you await each one. Its list_all() is an async iterator. create always sends an Idempotency-Key, so the SDK can retry it without creating a second monitor. For queries, schedules and result fields, see Monitors.

Verify webhooks

Needs SDK 0.2.0 or later. The latest release on PyPI is 0.1.5. Until a newer release is out, verify the signature without the SDK, as Verify a webhook describes. Check each webhook delivery’s signature before you act on it. Call verify_webhook(payload, headers, secret, *, tolerance=300), imported from keenable. It needs no client and no API key. Pass the request body exactly as received, as bytes or str. Parsing and re-encoding the JSON changes the bytes and breaks the signature. Answer a failed check with 400 and don’t act on the delivery. Drop repeated deliveries by the event’s ID, which stays the same across retries. For a complete handler, see Verify a webhook.

Errors

The Python SDK raises typed errors. Before an error reaches your code, the SDK retries the request, by default up to 2 times, when the Retryable column says yes. If the API’s error body sets retryable, that value decides instead of the status code. The Monitors update, trigger and bulk calls are retried only on a 429, which the API sends before it changes anything, because repeating them after another error could apply the change twice. For what each status code means and how to fix it, see Errors. An API error carries what the API said about the failure: status_code, code, type, fix, retryable, retry_after_seconds, request_id, param, value and reason. Branch on the code, not on the message. This program sends a search that the API rejects with 400 and prints what the error carries:
main.py
You see the status, the code, the rejected parameter and value, and the fix:
Output

Async

Use AsyncKeenable when your code already runs on asyncio. It takes the same constructor settings as Keenable, and you await its search, fetch and monitors methods. To run a model’s tool call with it, use arun_tool_call in place of run_tool_call. If you pass your own HTTP client to AsyncKeenable, pass an httpx.AsyncClient. Open the client with async with, or call await client.aclose() when you finish, so the connection pool closes. For a complete program, see Async on the SDKs page.

Notes

  • To give a model web search as a tool, pass TOOLS to your chat completions client and run each call with run_tool_call. See Tool calling.
  • Keenable keeps a connection pool. Use it as a context manager, or call close() when you finish.
  • Before version 0.2.0, a number passed as timeout limits each httpx phase, such as connecting or one read, not the whole attempt.
  • Monitors and webhook verification arrived in version 0.2.0. To see what the version you installed includes, read the Python changelog.
  • Source and package: README, PyPI.