{
  "license": "CC BY 4.0",
  "licenseUrl": "https://creativecommons.org/licenses/by/4.0/",
  "recipe": {
    "slug": "api-timeout-rate-by-route",
    "title": "Calculate API Timeout Rate by Route",
    "testedWith": "Apache DataFusion 45.2.0",
    "lastReviewed": "2026-07-27"
  },
  "contract": {
    "tableName": "api_requests",
    "schema": [
      {
        "name": "timestamp_utc",
        "type": "Timestamp",
        "description": "Request completion time."
      },
      {
        "name": "route_template",
        "type": "Utf8",
        "description": "Stable matched route."
      },
      {
        "name": "outcome",
        "type": "Utf8",
        "description": "success, error, timeout, cancelled, or rate_limited."
      },
      {
        "name": "latency_ms",
        "type": "Float64",
        "description": "Observed request duration."
      }
    ]
  },
  "query": "SELECT\n  route_template,\n  COUNT(*) AS requests,\n  SUM(CASE WHEN outcome = 'timeout' THEN 1 ELSE 0 END) AS timeouts,\n  100.0 * SUM(CASE WHEN outcome = 'timeout' THEN 1 ELSE 0 END)\n    / NULLIF(COUNT(*), 0) AS timeout_rate_pct,\n  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms\nFROM api_requests\nWHERE timestamp_utc >= now() - INTERVAL '24 hours'\nGROUP BY route_template\nHAVING COUNT(*) >= 50\nORDER BY timeout_rate_pct DESC, requests DESC\nLIMIT 20;",
  "fixtureKind": "schema-example",
  "inputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "route_template": "/api/checkout",
      "outcome": "success",
      "latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "route_template": "/api/search",
      "outcome": "failed",
      "latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "route_template": "/api/projects/:id",
      "outcome": "success",
      "latency_ms": 312
    }
  ],
  "illustrativeInputRows": [
    {
      "timestamp_utc": "2026-07-28T10:00:00Z",
      "route_template": "/api/checkout",
      "outcome": "success",
      "latency_ms": 184
    },
    {
      "timestamp_utc": "2026-07-28T11:00:00Z",
      "route_template": "/api/search",
      "outcome": "failed",
      "latency_ms": 926
    },
    {
      "timestamp_utc": "2026-07-28T12:00:00Z",
      "route_template": "/api/projects/:id",
      "outcome": "success",
      "latency_ms": 312
    }
  ],
  "expectedOutput": {
    "columns": [
      "route_template",
      "requests",
      "timeouts",
      "timeout_rate_pct",
      "p95_latency_ms"
    ],
    "rows": [
      {
        "route_template": "/api/reports/export",
        "requests": 780,
        "timeouts": 31,
        "timeout_rate_pct": 3.97,
        "p95_latency_ms": 29400
      },
      {
        "route_template": "/api/projects/:id/sync",
        "requests": 2410,
        "timeouts": 22,
        "timeout_rate_pct": 0.91,
        "p95_latency_ms": 8420
      },
      {
        "route_template": "/api/search",
        "requests": 12140,
        "timeouts": 9,
        "timeout_rate_pct": 0.07,
        "p95_latency_ms": 680
      }
    ]
  },
  "notes": [
    "The compact input rows demonstrate field names and JSON types; they are not claimed to generate the displayed aggregate by themselves.",
    "The expected output is deterministic synthetic review data for the documented output shape.",
    "Adapt time windows, thresholds, identities, and business definitions before operational use."
  ]
}