What’s newRelease 11 · Nov 16, 2026Bring Ollive into your own productRead the changelog

Reference

Production guide.
Reliable by default. Yours to tune.

The SDK handles paging, retries and errors for you, so your integration stays small. Here’s how each one works, and how to tune it for your service.

Configure the client

client.py

import osfrom ollive import Ollive client = Ollive()                                      # reads OLLIVE_API_KEYclient = Ollive(api_key=os.environ["MY_OLLIVE_KEY"])   # or pass it yourselfclient = Ollive(timeout=10, max_retries=4)             # tune it for your service
OptionEnvironment variableDefault
api_keyOLLIVE_API_KEYYour API key.
base_urlOLLIVE_BASE_URLhttps://api.ollive.ai/api
timeout–30 seconds
max_retries–2
headers–Extra headers sent with every request.
httpx_client–Your own httpx.Client, for proxies, custom TLS or connection limits.

The client keeps a pool of connections, so create one and reuse it for the life of your process:

lifecycle.py

with Ollive() as client:    ... # or keep one client for the life of your processclient = Ollive()...client.close()

Need proxies, custom TLS or more connections? Bring your own httpx.Client:

custom_http.py

import httpxfrom ollive import Ollive client = Ollive(httpx_client=httpx.Client(timeout=20, limits=httpx.Limits(max_connections=50)))

Async

AsyncOllive has every method Ollive has, each one awaited. It fits straight into FastAPI, aiohttp or any asyncio service.

async_client.py

import asynciofrom ollive import AsyncOllive async def main() -> None:    async with AsyncOllive() as client:        async for agent in await client.agents.list():            print(agent.name) asyncio.run(main())

Pagination

List methods return an iterator that fetches the next page as you loop, so you never handle a cursor. Ask for include_total when you want the count across every page, for a heading or a progress bar.

every_run.py

runs = client.runs.list(limit=100, include_total=True)print(runs.response.total_count, "runs in total") for run in runs:  # every run, across every page    print(run.run_id, run.not_met_count)

Paging through results yourself, for an infinite scroll in your UI? Pass each response’s next_cursor back as cursor.

Retries and timeouts

Every call only reads, so it’s always safe to send again. The SDK retries dropped connections, timeouts, rate limits and server errors twice, waiting the time Ollive asks for in Retry-After or backing off from about half a second. Requests time out after 30 seconds. Change either for the whole client, or for one call:

tuning.py

client = Ollive(max_retries=4)                          # every requestclient.runs.list(request_options={"max_retries": 0})    # just this one client = Ollive(timeout=10)                             # every requestclient.runs.list(request_options={"timeout": 60})       # just this one

Rate limits apply to each API key on its own, so give each service its own key and one busy job never slows another.

Errors

Everything the SDK raises comes from one family, ollive.OlliveError, so one except can catch it all, and the specific ones are there when you need them.

Exceptions

OlliveError├── ApiError                   The API answered with an error status│   ├── BadRequestError        400│   ├── UnauthorizedError      401│   ├── ForbiddenError         403│   ├── NotFoundError          404│   ├── TooManyRequestsError   429│   └── InternalServerError    500└── ApiConnectionError         Ollive couldn’t be reached    └── ApiTimeoutError        The request timed out

An ApiError carries status_code, a stable code to branch on, a message for people, the param at fault, and the request_id to send support.

errors.py

import loggingimport ollive log = logging.getLogger(__name__) try:    run = client.runs.get(run_id)except ollive.NotFoundError:    run = Noneexcept ollive.ApiError as e:    log.warning("Ollive said %s: %s (request %s)", e.code, e.message, e.request_id)except ollive.ApiConnectionError:    log.warning("Ollive couldn’t be reached; we’ll try again on the next sync")
StatusExceptionWhat to do
400BadRequestErrorA parameter needs to change. e.param names it.
401UnauthorizedErrorThe key is missing, expired or revoked.
403ForbiddenErrorThe key isn’t tied to a workspace.
404NotFoundErrorget found nothing with that ID.
429TooManyRequestsErrorRetried for you. Raised if the wait is long, so your code decides when to try again.
5xxInternalServerErrorRetried for you. If it persists, send support the request_id.

Every code is listed on Errors.

Logging

Turn logging on with a level, and lines go to the standard Python logger named ollive, with your key redacted.

logging.py

client = Ollive(logging={"level": "debug"})

Versions and upgrades

The SDK follows semantic versioning. It accepts fields and values Ollive adds later, so a new Ollive release never breaks the version you’ve installed, and you upgrade on your own schedule. The current version is 0.1.0. Pin a compatible range in your requirements:

requirements.txt

ollive>=0.1,<0.2

Each release is announced on the changelog.

← Building blocksAPI reference →