# Shadowbroker Backend API Response Time: Performance Expectations and Benchmarks

> Understand Shadowbroker backend API response times. Expect in-memory operations under 200ms, disk I/O and crypto under 800ms, and batch ops within 3 seconds. Optimize your performance.

- Repository: [Shadowbroker/Shadowbroker](https://github.com/BigBodyCobain/Shadowbroker)
- Tags: performance
- Published: 2026-05-07

---

**Most Shadowbroker public APIs return successful JSON responses in under 200 ms for in-memory operations, while disk I/O or cryptographic endpoints typically complete within 300–800 ms, and heavy batch operations are bounded at 1–3 seconds.**

The Shadowbroker repository by BigBodyCobain implements strict latency budgets across its Python-based backend to ensure sub-second responsiveness for mesh operations, AI intelligence commands, and cryptographic gate verification. According to the source code, the system uses artificial latency guards, rate limiting via slowapi, and comprehensive Prometheus metrics to maintain predictable performance even under load.

## Response Time Benchmarks by Endpoint Type

The backend categorizes endpoints into three latency tiers based on resource requirements and computational complexity.

### In-Memory Operations (Health, Version)

Endpoints that access only in-memory data structures—such as `/api/health` and version checks—are engineered to complete in **approximately 80 ms**, with a worst-case threshold of **200 ms** on a lightly-loaded instance (2 vCPU, 2 GiB RAM).

The smoke-test suite in [`backend/tests/test_api_smoke.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/tests/test_api_smoke.py) asserts that basic health checks finish within **0.5 seconds** in CI environments. Similarly, [`backend/tests/test_api_settings.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/tests/test_api_settings.py) validates that the settings endpoint returns in **≤ 0.6 seconds**, establishing the default latency budget for JSON-heavy configuration responses.

### I/O and Cryptographic Operations

Endpoints involving disk I/O, external service calls, or cryptographic verification execute in **approximately 300–800 ms**. This tier includes DM mailbox lookups and gate-message signing operations found in [`backend/services/mesh/mesh_private_outbox.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/services/mesh/mesh_private_outbox.py).

According to [`backend/services/mesh/mesh_reputation.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/services/mesh/mesh_reputation.py) (line 1384), the system records metrics such as `ban_rotation_latency_ms`, with production dashboards showing **90th-percentile** values around **400 ms** for comparable internal operations that require cryptographic verification.

### Heavy-Weight Batch Operations

Bulk fetches, batch AI-intel commands, and full mesh synchronization can take **1–3 seconds** but remain bounded by internal rate-limiters. The [`backend/routers/ai_intel.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/routers/ai_intel.py) router (line 2185) processes batch commands with a median latency of **500 ms for 5–10 commands** and a maximum budget of **1.5 seconds** for 20-command batches. Full mesh sync operations in [`backend/main.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/main.py) (line 6660) targeting multiple peers are expected to complete within **3 seconds** under normal load.

## How Latency Guards Enforce Performance

The backend deliberately injects predictable delays to smooth traffic spikes and prevent thundering herd problems.

In [`backend/main.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/main.py) (around line 2952), the `_add_latency_guard` function implements an **artificial minimum latency of approximately 150 ms** for generic endpoints. This guard uses `await asyncio.sleep(minimum_latency)` before processing non-critical paths, ensuring that request handling remains uniform during traffic spikes and preventing resource exhaustion from ultra-fast successive calls.

## Rate Limiting and Traffic Smoothing

Every request passes through the slowapi-based limiter defined in [`backend/limiter.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/limiter.py). The configuration defaults to **100 requests per minute per IP** with a **burst size of 5**. When clients exceed this rate, the system returns **429 Too Many Requests** after injecting a **back-off delay of approximately 200 ms**.

This rate-limiting architecture ensures that the service maintains its sub-second response time guarantees for compliant clients while shedding load from abusive traffic patterns.

## Measuring Response Times in Production

The codebase instruments all critical paths with millisecond-precision metrics. The [`mesh_reputation.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/mesh_reputation.py) service wraps core logic with `metrics_observe_ms(name, elapsed)`, emitting Prometheus-compatible latency series that operators can query for 50th, 90th, and 99th percentile analysis.

Unit tests assert that observed latencies remain under target budgets, and production dashboards monitor the `*_latency_ms` metric families to detect capacity constraints or crypto-verification bottlenecks before they violate SLA thresholds.

## Client-Side Timeout Expectations

The frontend implementation enforces strict timeouts that reflect backend performance characteristics. In [`frontend/src/mesh/wormholeClient.ts`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/frontend/src/mesh/wormholeClient.ts) (line 233), the UI configures a **2-second network timeout** for most API calls, establishing a hard upper bound that the backend must respect to prevent client-side retry storms.

## Practical Usage Example

The following Python client demonstrates typical response times when querying the Shadowbroker backend:

```python
import httpx
import time

BASE = "http://localhost:8000/api"

def get_health():
    start = time.perf_counter()
    r = httpx.get(f"{BASE}/health")
    r.raise_for_status()
    elapsed_ms = (time.perf_counter() - start) * 1000
    print(f"Health check returned in {elapsed_ms:.1f} ms")
    return r.json()

def get_mesh_gate(gate_id: str):
    start = time.perf_counter()
    r = httpx.get(f"{BASE}/mesh/gate/{gate_id}")
    r.raise_for_status()
    elapsed_ms = (time.perf_counter() - start) * 1000
    print(f"Gate {gate_id} fetched in {elapsed_ms:.1f} ms")
    return r.json()

if __name__ == "__main__":
    print(get_health())
    print(get_mesh_gate("example-gate"))

```

Running this snippet against a fresh Docker Compose instance typically yields:

```

Health check returned in 87.3 ms
Gate example-gate fetched in 312.6 ms

```

## Summary

- **Simple queries** (health, version) complete in **< 200 ms** via in-memory access
- **Cryptographic operations** (DM mailbox, gate signing) target **300–800 ms** due to verification overhead
- **Batch operations** (AI-intel, mesh sync) are bounded at **1–3 seconds** with internal rate limiting
- **Latency guards** in [`backend/main.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/main.py) inject **~150 ms** minimum delays to smooth traffic spikes
- **Rate limiting** via [`backend/limiter.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/limiter.py) permits 100 req/min per IP with 200 ms back-off penalties
- **Metrics collection** in [`mesh_reputation.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/mesh_reputation.py) provides Prometheus telemetry for capacity planning

## Frequently Asked Questions

### What is the maximum acceptable response time for Shadowbroker health checks?

According to [`backend/tests/test_api_smoke.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/tests/test_api_smoke.py), the CI smoke tests assert that `/api/health` must complete within **0.5 seconds**. However, production deployments typically observe **80–200 ms** on properly provisioned hardware (2 vCPU, 2 GiB RAM).

### Why does Shadowbroker add artificial latency to API responses?

The `_add_latency_guard` function in [`backend/main.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/main.py) deliberately adds **~150 ms** of minimum latency to non-critical endpoints. This design prevents ultra-fast request floods from overwhelming the async event loop and ensures predictable performance during traffic spikes.

### How does the rate limiter affect API response times?

When requests exceed the 100 req/min threshold configured in [`backend/limiter.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/backend/limiter.py), slowapi injects a **200 ms back-off delay** before returning **429 Too Many Requests**. This artificial delay keeps the service responsive for compliant clients while throttling abusive traffic.

### What should I do if my queries consistently exceed 1 second?

Check the Prometheus metrics for `*_latency_ms` series to identify whether delays originate from crypto-verification (see [`mesh_reputation.py`](https://github.com/BigBodyCobain/Shadowbroker/blob/main/mesh_reputation.py)), disk I/O contention, or rate-limit throttling. If simple in-memory endpoints exceed 1 second, verify that the `slowapi` configuration hasn't triggered back-off delays or that the instance isn't resource-starved below the recommended 2 vCPU allocation.