Telemetry
API reliability SQL recipe

Calculate API Timeout Rate by Route

Rank routes by timeout rate while preserving request volume and configured timeout boundaries.

Beginnerapi_requestsReviewed 2026-07-27Tested with Apache DataFusion 45.2.0

Question answered

Which API routes time out often enough to affect users?

Timeouts deserve their own rate because they may surface as several status codes or client disconnects. A normalized outcome field makes them comparable.

Event contract

Fields the query expects

FieldTypeWhy it exists
timestamp_utcTimestampRequest completion time.
route_templateUtf8Stable matched route.
outcomeUtf8success, error, timeout, cancelled, or rate_limited.
latency_msFloat64Observed request duration.
DataFusion SQL

Copy the query

sql
SELECT
  route_template,
  COUNT(*) AS requests,
  SUM(CASE WHEN outcome = 'timeout' THEN 1 ELSE 0 END) AS timeouts,
  100.0 * SUM(CASE WHEN outcome = 'timeout' THEN 1 ELSE 0 END)
    / NULLIF(COUNT(*), 0) AS timeout_rate_pct,
  approx_percentile_cont(latency_ms, 0.95) AS p95_latency_ms
FROM api_requests
WHERE timestamp_utc >= now() - INTERVAL '24 hours'
GROUP BY route_template
HAVING COUNT(*) >= 50
ORDER BY timeout_rate_pct DESC, requests DESC
LIMIT 20;

This read-only query is planned and executed against an empty typed table with Apache DataFusion 45.2.0. The deterministic sample output is synthetic and reviewed separately; validate field types, thresholds, and business definitions against your own data. Read the testing methodology.

Query result

Timeout rate by route

Report export has a timeout problem that an aggregate 5xx rate could hide.

route_templaterequeststimeoutstimeout_rate_pctp95_latency_ms
/api/reports/export780313.9729,400
/api/projects/:id/sync2,410220.918,420
/api/search12,14090.07680

Synthetic example output. Run the query against your own event schema and thresholds before using it for operational decisions.

How the SQL works

  1. 1A normalized outcome captures server deadlines, gateway timeouts, and handled client timeout paths.
  2. 2The minimum request threshold keeps one rare timeout from dominating the ranking.
  3. 3p95 latency beside the timeout rate helps distinguish consistently slow work from abrupt deadline failures.

Edge cases to decide

  • Client disconnects and server deadlines may need different outcome values.
  • Long-running exports can have a different service objective from interactive routes.
  • Record the configured deadline when routes or customers use different timeout policies.

Recommended dashboard

  • Bars: timeout_rate_pct by route_template
  • Trend: timeout volume and p95 latency
  • Table: newest timed-out requests with dependency and release context

Alert guidance

Alert when a route exceeds its timeout-rate objective at meaningful request volume.

Read alert setup

Put the recipe to work

Related instrumentation and guides

Continue the analysis

Run it on real events

Create a table, adapt the fields, and save the result

Start free, send structured events, and use the query result as a chart, shared dashboard widget, or alert input.

Get an API key