openapi: 3.2.0 info: title: LiteLLM Health API description: "Enterprise Edition \n\nProxy Server to call 100+ LLMs in the OpenAI format. [**Customize Swagger Docs**](https://docs.litellm.ai/docs/proxy/enterprise#swagger-docs---custom-routes--branding)\n\n\U0001F449 [```LiteLLM Admin Panel on /ui```](/ui). Create, Edit Keys with SSO. Having issues? Try [```Fallback Login```](/fallback/login)\n\n\U0001F4B8 [```LiteLLM Model Cost Map```](https://models.litellm.ai/).\n\n\U0001F50E [```LiteLLM Model Hub```](/ui/model_hub_table). See available models on the proxy. [**Docs**](https://docs.litellm.ai/docs/proxy/ai_hub)" version: 1.95.0 x-operator: institution x-provenance: method: probed source: https://llmproxy.uva.nl/openapi.json retrieved: '2026-08-19' note: Document is generated by the LiteLLM proxy software the University of Amsterdam self-hosts; the deployment, the key issuance and the host (llmproxy.uva.nl, UvA Azure) are the institution's. servers[] added by API Evangelist because the served document omits it; nothing else altered. servers: - url: https://llmproxy.uva.nl description: University of Amsterdam / Amsterdam University of Applied Sciences shared AI gateway tags: - name: health paths: /test: get: tags: - health summary: Test Endpoint description: "[DEPRECATED] use `/health/liveliness` instead.\n\nA test endpoint that pings the proxy server to check if it's healthy.\n\nParameters:\n request (Request): The incoming request.\n\nReturns:\n dict: A dictionary containing the route of the request URL." operationId: test_endpoint_test_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/services: get: tags: - health summary: Health Services Endpoint description: 'Use this admin-only endpoint to check if the service is healthy. Example: ``` curl -L -X GET ''http://0.0.0.0:4000/health/services?service=datadog'' -H ''Authorization: Bearer sk-1234'' ```' operationId: health_services_endpoint_health_services_get security: - APIKeyHeader: [] parameters: - name: service in: query required: true schema: anyOf: - enum: - slack_budget_alerts - langfuse - langfuse_otel - slack - openmeter - webhook - email - braintrust - datadog - datadog_llm_observability - generic_api - arize - galileo - newrelic - sqs type: string - type: string description: Specify the service being hit. title: Service description: Specify the service being hit. responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /health: get: tags: - health summary: Health Endpoint description: "\U0001F6A8 USE `/health/liveliness` to health check the proxy \U0001F6A8\n\nSee more \U0001F449 https://docs.litellm.ai/docs/proxy/health\n\n\nCheck the health of all the endpoints in config.yaml\n\nTo run health checks in the background, add this to config.yaml:\n```\ngeneral_settings:\n # ... other settings\n background_health_checks: True\n```\nelse, the health checks will be run on models when /health is called.\n\nTo skip deployments that set ``model_info.disable_background_health_check: true``\non ``GET /health`` as well as in the background loop, set\n``general_settings.health_check_skip_disabled_background_models: true``." operationId: health_endpoint_health_get security: - APIKeyHeader: [] parameters: - name: model in: query required: false schema: anyOf: - type: string - type: 'null' description: Specify the model name (optional) title: Model description: Specify the model name (optional) - name: model_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Specify the model ID (optional) title: Model Id description: Specify the model ID (optional) responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /health/history: get: tags: - health summary: Health Check History Endpoint description: 'Get health check history for models Returns historical health check data with optional filtering.' operationId: health_check_history_endpoint_health_history_get security: - APIKeyHeader: [] parameters: - name: model in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by specific model name title: Model description: Filter by specific model name - name: status_filter in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter by status (healthy/unhealthy) title: Status Filter description: Filter by status (healthy/unhealthy) - name: limit in: query required: false schema: type: integer maximum: 1000 minimum: 1 description: Number of records to return default: 100 title: Limit description: Number of records to return - name: offset in: query required: false schema: type: integer minimum: 0 description: Number of records to skip default: 0 title: Offset description: Number of records to skip responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /health/latest: get: tags: - health summary: Latest Health Checks Endpoint description: 'Get the latest health check status for all models Returns the most recent health check result for each model.' operationId: latest_health_checks_endpoint_health_latest_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/shared-status: get: tags: - health summary: Shared Health Check Status Endpoint description: 'Get the status of shared health check coordination across pods. Returns information about Redis connectivity, lock status, and cache status.' operationId: shared_health_check_status_endpoint_health_shared_status_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/license: get: tags: - health summary: Health License Endpoint description: Return metadata about the configured LiteLLM license without exposing the key. operationId: health_license_endpoint_health_license_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /active/callbacks: get: tags: - health summary: Active Callbacks description: "Returns a list of litellm level settings\n\nThis is useful for debugging and ensuring the proxy server is configured correctly.\n\nResponse schema:\n```\n{\n \"alerting\": _alerting,\n \"litellm.callbacks\": litellm_callbacks,\n \"litellm.input_callback\": litellm_input_callbacks,\n \"litellm.failure_callback\": litellm_failure_callbacks,\n \"litellm.success_callback\": litellm_success_callbacks,\n \"litellm._async_success_callback\": litellm_async_success_callbacks,\n \"litellm._async_failure_callback\": litellm_async_failure_callbacks,\n \"litellm._async_input_callback\": litellm_async_input_callbacks,\n \"all_litellm_callbacks\": all_litellm_callbacks,\n \"num_callbacks\": len(all_litellm_callbacks),\n \"num_alerting\": _num_alerting,\n \"litellm.request_timeout\": litellm.request_timeout,\n}\n```" operationId: active_callbacks_active_callbacks_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /settings: get: tags: - health summary: Active Callbacks description: "Returns a list of litellm level settings\n\nThis is useful for debugging and ensuring the proxy server is configured correctly.\n\nResponse schema:\n```\n{\n \"alerting\": _alerting,\n \"litellm.callbacks\": litellm_callbacks,\n \"litellm.input_callback\": litellm_input_callbacks,\n \"litellm.failure_callback\": litellm_failure_callbacks,\n \"litellm.success_callback\": litellm_success_callbacks,\n \"litellm._async_success_callback\": litellm_async_success_callbacks,\n \"litellm._async_failure_callback\": litellm_async_failure_callbacks,\n \"litellm._async_input_callback\": litellm_async_input_callbacks,\n \"all_litellm_callbacks\": all_litellm_callbacks,\n \"num_callbacks\": len(all_litellm_callbacks),\n \"num_alerting\": _num_alerting,\n \"litellm.request_timeout\": litellm.request_timeout,\n}\n```" operationId: active_callbacks_settings_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/readiness: get: tags: - health summary: Health Readiness description: 'Public readiness probe. Returns a low-detail payload safe to expose to unauthenticated load balancers — `status` plus `db` so orchestrators and external probes can distinguish "healthy" from "DB unreachable" without a credential. Admins can opt into the legacy detailed payload with general_settings.allow_public_health_readiness_details.' operationId: health_readiness_health_readiness_get responses: '200': description: Successful Response content: application/json: schema: {} options: tags: - health summary: Health Readiness Options description: Options endpoint for health/readiness check. operationId: health_readiness_options_health_readiness_options responses: '200': description: Successful Response content: application/json: schema: {} /health/readiness/details: get: tags: - health summary: Health Readiness Details description: Authenticated readiness diagnostics with DB/cache/callback metadata. operationId: health_readiness_details_health_readiness_details_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/backlog: get: tags: - health summary: Health Backlog description: 'Returns the number of HTTP requests currently in-flight on this uvicorn worker. Use this to measure per-pod queue depth. A high value means the worker is processing many concurrent requests — requests arriving now will have to wait for the event loop to get to them, adding latency before LiteLLM even starts its own timer.' operationId: health_backlog_health_backlog_get responses: '200': description: Successful Response content: application/json: schema: {} security: - APIKeyHeader: [] /health/drain: get: tags: - health summary: Health Drain description: "Graceful-drain probe for Kubernetes ``preStop`` hooks.\n\nDisabled by default and returns 404 unless ``general_settings`` sets\n``enable_drain_endpoint: true``. Calling it flips a process-wide\nshutting-down flag, so a successful call permanently takes the worker out\nof rotation until the pod restarts.\n\nBecause the kubelet calls preStop hooks without proxy credentials, the\nendpoint does not require ``user_api_key_auth``. To prevent any\npod-reachable caller from triggering shutdown, set\n``general_settings.drain_endpoint_token`` (or the ``DRAIN_ENDPOINT_TOKEN``\nenv var) and supply the same value on the ``X-Drain-Token`` header from\nthe preStop hook. Calls without the header (or with a wrong value) get a\n401 and have no side effect.\n\nWhen enabled, it marks the worker as shutting down (so /health/readiness\nand /health/liveliness immediately start returning 503, removing the pod\nfrom service) and blocks until the in-flight request counter drains to\nzero or ``GRACEFUL_SHUTDOWN_TIMEOUT`` elapses. Unlike a fixed ``sleep``,\nthis returns as soon as real in-flight work is done.\n\nWire it up as:\n\n```yaml\nlifecycle:\n preStop:\n httpGet:\n path: /health/drain\n port: 4000\n httpHeaders:\n - name: X-Drain-Token\n value: \n```" operationId: health_drain_health_drain_get responses: '200': description: Successful Response content: application/json: schema: {} /health/liveness: get: tags: - health summary: Health Liveliness description: 'Unprotected endpoint for checking if worker is alive. Returns 503 once graceful shutdown has begun so Kubernetes stops counting the draining pod as live and terminates it on schedule.' operationId: health_liveliness_health_liveness_get responses: '200': description: Successful Response content: application/json: schema: {} options: tags: - health summary: Health Liveliness Options description: Options endpoint for health/liveliness check. operationId: health_liveliness_options_health_liveness_options responses: '200': description: Successful Response content: application/json: schema: {} /health/liveliness: get: tags: - health summary: Health Liveliness description: 'Unprotected endpoint for checking if worker is alive. Returns 503 once graceful shutdown has begun so Kubernetes stops counting the draining pod as live and terminates it on schedule.' operationId: health_liveliness_health_liveliness_get responses: '200': description: Successful Response content: application/json: schema: {} options: tags: - health summary: Health Liveliness Options description: Options endpoint for health/liveliness check. operationId: health_liveliness_options_health_liveliness_options responses: '200': description: Successful Response content: application/json: schema: {} /health/test_connection: post: tags: - health summary: Test Model Connection description: "Test a direct connection to a specific model.\n\nThis endpoint allows you to verify if your proxy can successfully connect to a specific model.\nIt's useful for troubleshooting model connectivity issues without going through the full proxy routing.\n\nExample:\n```bash\n# If model is configured in proxy_config.yaml, you only need to specify the model name:\ncurl -X POST 'http://localhost:4000/health/test_connection' \\\n -H 'Authorization: Bearer sk-1234' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"litellm_params\": {\n \"model\": \"gpt-4o\"\n },\n \"mode\": \"chat\"\n }'\n\n# The endpoint will automatically use api_key, api_base, etc. from proxy_config.yaml\n\n# You can also override specific params or test with custom credentials:\ncurl -X POST 'http://localhost:4000/health/test_connection' \\\n -H 'Authorization: Bearer sk-1234' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"litellm_params\": {\n \"model\": \"azure/gpt-4o\",\n \"api_key\": \"os.environ/AZURE_OPENAI_API_KEY\",\n \"api_base\": \"os.environ/AZURE_OPENAI_ENDPOINT\",\n \"api_version\": \"2024-10-21\"\n },\n \"mode\": \"chat\"\n }'\n```\n\nNote: \n- If the model is configured in proxy_config.yaml, credentials (api_key, api_base, etc.) \n will be automatically loaded from the config (with resolved environment variables).\n- You can override specific params by including them in the request.\n- You can use `os.environ/VARIABLE_NAME` syntax to reference environment variables,\n which will be resolved automatically (same as in proxy_config.yaml).\n\nReturns:\n dict: A dictionary containing the health check result with either success information or error details." operationId: test_model_connection_health_test_connection_post requestBody: content: application/json: schema: $ref: '#/components/schemas/Body_test_model_connection_health_test_connection_post' responses: '200': description: Successful Response content: application/json: schema: {} '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' security: - APIKeyHeader: [] components: schemas: HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError Body_test_model_connection_health_test_connection_post: properties: mode: anyOf: - type: string enum: - chat - completion - embedding - audio_speech - audio_transcription - image_generation - video_generation - batch - rerank - realtime - responses - ocr - type: 'null' title: Mode description: The mode to test the model with. If not provided, auto-detected from model capabilities. litellm_params: additionalProperties: true type: object title: Litellm Params description: Parameters for litellm.completion, litellm.embedding for the health check model_info: additionalProperties: true type: object title: Model Info description: Model info for the health check type: object title: Body_test_model_connection_health_test_connection_post securitySchemes: APIKeyHeader: type: apiKey description: Bearer token in: header name: x-litellm-api-key