Appearance
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 usefullypython
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.
| Method | Endpoint |
|---|---|
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).