Status-aware LLM routing for more reliable agents and coding CLIs. Pre-flight health checks, automatic fallback across providers, and tier-based routing — with one unified API.
Set at least one provider API key, then route by model name. If the primary provider is unavailable, aistatus will try compatible providers that are both healthy and configured in your environment.
python
from aistatus import route
resp = route(
"Summarize the latest deployment status.",
model="claude-sonnet-4-6",
)
print(resp.content)
print(resp.model_used)
print(resp.provider_used)
print(resp.was_fallback)
print(resp.fallback_reason)
How It Works
1Auto-discovers providers from environment variables, or you register them manually.
2Before sending a request, queries aistatus.cc for provider/model status and compatible alternatives.
3If the primary route is healthy, uses it directly.
4If the primary route is unavailable or a provider call fails, automatically tries the next available provider.
5The actual LLM request is executed through your provider SDK — not proxied through aistatus.
6Returns a unified RouteResponse with the chosen model, provider, and fallback metadata.
If the status API is unreachable, the router falls back to model-prefix guessing and only uses adapters available locally.
Tier Routing
Define ordered model groups and let the router try them in sequence. A good fit when you want stable behavioral buckets like fast, standard, or premium without hard-coding one vendor per workflow step.
python
from aistatus import Router
router = Router(check_timeout=2.0)
router.add_tier("fast", [
"claude-haiku-4-5",
"gpt-4o-mini",
"gemini-2.0-flash",
])
router.add_tier("standard", [
"claude-sonnet-4-6",
"gpt-4o",
"gemini-2.5-pro",
])
resp = router.route(
"Explain quantum computing in one sentence.",
tier="fast",
)
Agent Pipeline
Especially useful for multi-step agents. Use different model tiers for planning, research, and synthesis. Each call is independently routed with health checks and fallback.
python
from aistatus import route
plan = route(
"How is embodied AI changing manufacturing?",
model="claude-haiku-4-5",
system="Break the topic into 3 research sub-questions. Be concise.",
)
answer = route(
plan.content,
model="claude-sonnet-4-6",
prefer=["anthropic", "google"],
)
Supported Providers
The router auto-discovers providers from standard environment variables. OpenAI-compatible providers reuse the openai Python client under the hood.
Provider
Environment Variable
Notes
Anthropic
ANTHROPIC_API_KEY
Claude models
OpenAI
OPENAI_API_KEY
GPT models
Google Gemini
GEMINI_API_KEY
Gemini models
OpenRouter
OPENROUTER_API_KEY
Multi-provider gateway
DeepSeek
DEEPSEEK_API_KEY
OpenAI-compatible
Mistral
MISTRAL_API_KEY
OpenAI-compatible
xAI
XAI_API_KEY
OpenAI-compatible
Groq
GROQ_API_KEY
OpenAI-compatible
Together
TOGETHER_API_KEY
OpenAI-compatible
Moonshot
MOONSHOT_API_KEY
OpenAI-compatible
Qwen / DashScope
DASHSCOPE_API_KEY
OpenAI-compatible
Manual Registration
Register custom providers directly when auto-discovery is not enough. Useful for self-hosted gateways or OpenAI-compatible endpoints.
Query aistatus.cc directly without sending any model request. Useful for dashboards, health checks, pre-deployment validation, or building your own routing policy.
python
from aistatus import StatusAPI
api = StatusAPI()
check = api.check_provider("anthropic")
print(check.status)
print(check.is_available)
for provider in api.providers():
print(provider.name, provider.status.value)
for model in api.search_models("sonnet"):
print(model.id, model.prompt_price, model.completion_price)
Gateway
A local HTTP proxy that sits between your application and provider APIs. Adds multi-key rotation, automatic failover, per-model health tracking, protocol translation, and usage recording — all transparent to the calling application.
Quick Start
python
pip install aistatus[gateway]
python -m aistatus.gateway start --auto
# Point your tools at the gateway
export ANTHROPIC_BASE_URL=http://localhost:9880/anthropic
export OPENAI_BASE_URL=http://localhost:9880/openai/v1
When a request arrives, the gateway tries three layers in order:
1Managed keys — Tries configured API keys in round-robin order
2Passthrough — If hybrid mode is enabled (default), tries the caller's own API key
3Fallbacks — Tries secondary providers in order
If a backend returns a retryable error (429, 500, 502, 503, 529), the gateway marks it unhealthy with a cooldown and tries the next backend.
Key Features
Feature
Description
Model Fallbacks
Per-model fallback chains downgrade gracefully when a specific model is degraded
Protocol Translation
Translates between Anthropic and OpenAI formats — route Anthropic calls to OpenAI-compatible backends
Config Modes
Maintain production/development configurations and switch at runtime via API or per-request
Health Tracking
Sliding 60-second error window with status-code-specific cooldowns at backend and model level
Gateway Auth
Protect the gateway with dedicated API keys, separate from provider keys
Usage Tracking
Per-model and per-provider cost breakdown with configurable time periods
Management Endpoints
Endpoint
Method
Description
/health
GET
Quick health check (always public)
/status
GET
Detailed backend and model health
/usage
GET
Usage tracking with cost breakdown
/mode
POST
Switch active configuration mode
Programmatic Usage
python
from aistatus.gateway import start
start(config_path="gateway.yaml", host="127.0.0.1", port=9880)
Response Object
Every route() call returns a RouteResponse. The routing metadata makes it easy to log fallback events and understand how stable your agent or CLI is in real traffic.
python
@dataclass
class RouteResponse:
content: str
model_used: str
provider_used: str
was_fallback: bool
fallback_reason: str | None = None
input_tokens: int = 0
output_tokens: int = 0
cost_usd: float = 0.0
raw: Any = None
Error Handling
python
from aistatus import AllProvidersDown, ProviderNotInstalled, route
try:
resp = route("Hello", model="claude-sonnet-4-6")
except AllProvidersDown as e:
print(e.tried)
except ProviderNotInstalled as e:
print(f"Install support for: {e.provider}")
Common Failure Modes
AllProvidersDownNo configured provider could successfully serve the call
ProviderNotInstalledThe required provider SDK extra is missing
ProviderCallFailedThe selected provider failed and fallback was disabled