Agents and automation

Connect

Direct cloud access uses the native API at https://ollama.com/api/chat, with the header Authorization: Bearer $OLLAMA_API_KEY. The OpenAI-compatible base URL is https://ollama.com/v1. It serves chat completions and stateless responses. No Ollama install is needed.

base_url = https://ollama.com/v1
Authorization: Bearer $OLLAMA_API_KEY
model    = gemma4:31b      # a name from https://ollama.com/api/tags

Model names for direct API calls come from https://ollama.com/api/tags, for example gemma4:31b. In the Ollama app and CLI, use the :cloud suffix instead, for example gemma4:cloud.

Errors: 429 and 502

• 429 means rate limit exceeded. Back off, then retry, with a longer gap each time.
• 502 means the cloud model is unreachable. Retry with backoff, or switch to another model.
• Errors are JSON with an error field, for example {“error”: “…”}.
• Streams fail differently. A mid-stream error arrives as an NDJSON object with an error field, and the HTTP status does not change. Read the body of a stream, not only its status.

A monthly-limit 429 reads differently. It says you have reached your monthly usage limit. Retrying will not help until the reset or until credits are added. See When capped.

A fallback chain

A fallback chain tries one model, moves to the next when a call fails with 429 or 502, and ends on a local model that you run yourself.

1. Try model A. A success ends the chain.
2. On 429 or 502, switch to model B and back off before the next try, with a longer gap each time.
3. If model B fails the same way, use a local model.
4. If the error says monthly usage limit, stop calling the cloud. Retrying in a loop only adds failed calls until the reset.

Working Python and JavaScript versions of this chain are in the setup recipes.

What the cloud API does not support

• Stateful Responses. Keep the conversation on your side and send what the model needs with each request.
• Built-in web search through /v1/responses. Run your own search tool and pass its results in.
• Freeform, custom tool-call replay. Use function tools.

The Anthropic-compatible endpoint, /v1/messages, is on the local server only, at http://localhost:11434.

Keep keys out of browsers

Your API key is a secret. Anything in browser code is public. Call Ollama from your server or a worker, read the key from the environment as OLLAMA_API_KEY, and keep it out of source control.

Watch the usage API from automation

• The usage API allows about five reads a minute. Past that it returns 429 “too many requests”. Space your reads 12 seconds apart. Eight seconds is too fast.
• Ranges are 24h, 7d and 30d. 24h gives hourly buckets, and 7d and 30d give daily buckets. Any other range returns 400.
• The usage settings page shows upcoming model retirements for the models you used recently. Check it before you hard-code a model name.