Status & Uptime

This page tells agents how to check whether Krawl is healthy and how to recover gracefully when it isn't.

Service statusCopy Anchor Link

• Live status page (human): https://docs.krawl.sh/status — real-time component status, API version, uptime, and probe latency (probes the API health endpoint on every load).
• Status JSON (programmatic): https://docs.krawl.sh/status.json — machine-readable status with per-component state, so agents can determine retry eligibility.
• Health endpoint (programmatic): https://api.krawl.sh/health — a fast, unauthenticated liveness/readiness check suitable for automated probes.

What the status probe establishesCopy Anchor Link

The page and JSON endpoint use the same bounded health probe. A successful HTTP status alone is insufficient: both status: "ok" and db: "ok" must be present to show operational. HTTP errors and degraded payloads show degradation; invalid or missing payloads show unknown. Only allowlisted health fields are exposed; raw errors and arbitrary upstream fields are discarded.

MCP, research providers, payment settlement and webhooks are not independently probed by /health. MCP is therefore unknown, even while API health is green. There is no incident timeline or historical availability measurement. API uptime is the current process uptime, not a measured service SLO. The existing page refreshes on request and does not create new status infrastructure.

The /health endpointCopy Anchor Link

GET /health requires no auth and reports liveness, version, and database connectivity:

curl https://api.krawl.sh/health

{
  "status": "ok",
  "version": "0.2.0",
  "db": "ok",
  "uptime_seconds": 1234.5
}

Agent usage: Before a batch of work — or as a circuit-breaker probe after repeated failures — call /health. If status is degraded or the request fails/times out, back off and retry the probe rather than hammering the research endpoints. Keep probes lightweight (e.g. every 30–60s while degraded).

Error-recovery playbookCopy Anchor Link

When a request fails, decide your action from the HTTP status and the error envelope ({error_code, message, retry_after}):

Recommended loop for autonomous agents:

1. Probe /health if you're starting fresh or recovering from a failure streak.
2. Send the request, honoring X-RateLimit-Remaining to self-throttle.
3. On retryable failure (429/5xx), back off (exponential + jitter, capped), preferring the server's Retry-After hint. See the full retry playbook.
4. On a failure streak, open a circuit breaker: pause requests, poll /health until status: ok, then resume.
5. For long jobs, use POST /research/async + GET /tasks/{id} polling (or webhooks) so a dropped connection never loses work — the task keeps running server-side and the result is retrievable via GET /results/{id}.

Idempotency & not losing workCopy Anchor Link

• Async tasks and lookouts run server-side. If your client crashes, the work continues; re-fetch state with GET /tasks/{id} or GET /lookouts/{id}.
• Webhook deliveries are best-effort and may be duplicated — deduplicate on task_id/lookout_id + event. See Webhooks.