Skip to content

Python SDK ​

First release

The API currently serves chat, web search and page reading. SDK methods for other features (embeddings, crawl, research, sandbox, browser, files) return a 404 error until those features are switched on.

bash
pip install usefully
python
from usefully import Usefully

client = Usefully()  # reads USEFULLY_API_KEY
reply = client.chat.completions.create(
    model="anthropic/claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Hello"}],
)
print(reply.choices[0].message.content)

Python 3.9+, one dependency (httpx), fully typed. AsyncUsefully offers the same methods with await. Responses are dicts that also allow attribute access.

MethodEndpoint
client.chat.completions.create(model=…, messages=…, **params)POST /v1/chat/completions (returns a Stream with stream=True)
client.embeddings.create(model=…, input=…)POST /v1/embeddings
client.search(query=…, **params)POST /v1/search
client.research(question=…, depth=…)POST /v1/research (then client.jobs.wait)
client.sandbox.run(code=…, language=…)POST /v1/sandbox/run
client.browser.sessions.create() / .retrieve() / .list() / .release()/v1/browser/sessions…
client.models.list()GET /v1/models
client.key.retrieve()GET /v1/key
client.billing.retrieve() / .checkout() / .update_settings()/v1/billing…

Errors are exception classes (usefully.InsufficientCreditsError, usefully.RateLimitError, …) with status, type, code and request_id. Connection errors, 408, 409, 429 and 5xx are retried twice with backoff (max_retries).