PostgREST API Latency p99 (ms), Supabase

​

At a glance

This card reports the 99th-percentile response time of requests served by PostgREST, the auto-generated REST layer in front of your Supabase database. Where p95 describes the experience of the unluckiest 1 in 20 requests, p99 describes the unluckiest 1 in 100: the far tail. It is the metric that catches the rare but severe stalls (a lock wait, a cold-cache scan, a connection that queued for a long time) which p95 smooths over. For a platform or SRE team, p99 is the gauge that exposes the requests your most demanding users and your slowest code paths actually hit. A healthy p95 with a blown-out p99 is one of the most useful diagnostic shapes you can read: most of the API is fine, but a thin slice of requests is hitting a specific, fixable problem.

​

Calculation

p99 = the latency value at the 99th percentile of all PostgREST
      request durations in the window
fire when: p99 > 500ms (sustained)

1. The far tail is noisier and more sample-sensitive. p99 is computed from the slowest 1% of requests, so on a low-traffic window it rests on very few data points and can jump around. On a high-traffic project it is stable and meaningful. Always read p99 with the request rate in view; a dramatic p99 on a handful of requests is far less significant than the same value across tens of thousands.
2. p99 surfaces tail-only causes that never touch p95. A single periodic lock, a cron-driven heavy query, a connection that queued for a long time during a brief pool exhaustion, or a cold-cache page read can push the slowest 1% out a long way while leaving the bulk of the distribution untouched. That is precisely the kind of intermittent, hard-to-reproduce problem this card is built to expose.

​

Worked example

1. p95 never moved, only p99 spiked, and then recovered. The bulk of the API was healthy throughout. A thin slice of requests hit a severe stall for one five-minute window and then it cleared. That on/off pattern points at a periodic event, not a sustained regression.
2. The timing is suspicious. The spike lands on a five-minute boundary, which often coincides with a scheduled job. Cross-reference Top 10 Slowest Queries; a reporting aggregation runs every five minutes and briefly locks rows that the portal’s read endpoints also touch.
3. The lock, not the query, is the cost. Deadlocks (last 5m) shows zero deadlocks (nothing aborted), but pg_stat_activity during the window shows portal requests in wait_event_type = 'Lock'. They were not failing, just waiting behind the aggregation, which is exactly how a tail-only p99 spike forms.

Confirm a periodic lock-wait tail:
  SELECT wait_event_type, wait_event, count(*)
  FROM pg_stat_activity
  WHERE state = 'active'
  GROUP BY 1, 2
  ORDER BY 3 DESC;
  -- during the spike window, expect Lock waits on the contended rows.

Find the periodic heavy query:
  SELECT query, calls, mean_exec_time, max_exec_time
  FROM pg_stat_statements
  ORDER BY max_exec_time DESC
  LIMIT 10;

Fixes, in order:
  1. Move the 5-minute aggregation off the hot rows (read from a replica,
     or run against a materialised view refreshed off-peak).
  2. If it must run live, reduce its lock footprint (smaller batches,
     SELECT ... FOR SHARE only where needed, shorter transactions).
  3. Stagger the schedule so it never overlaps a known traffic peak.

1. p99 is the periodic-stall detector. When p95 is calm but p99 spikes on a rhythm, look for a scheduled job, a cron, or a batch process contending with live traffic for locks or connections.
2. Always read p99 alongside the request rate. On low traffic the far tail rests on few samples and is noisy; the same value across high volume is a real, repeatable problem worth fixing.
3. A blown p99 with a healthy p95 is good news, not bad. It means the fix is targeted: a single query, schedule, or lock, not a systemic slowdown. The whole API does not need re-architecting; one tail-causing path does.

​

Sibling cards

​

Reconciling against the source

In the Supabase dashboard, open Reports → API and the Logs → API / Edge explorer for the per-route request-duration distribution PostgREST records. The dashboard latency charts and this card draw from the same request-log stream. Compute the p99 yourself from the project’s log explorer: the api_logs / edge request logs expose per-request response duration, which you can percentile at p99 over a matching window. Separate API time from database time with pg_stat_statements (max_exec_time is the closest single-statement proxy for tail behaviour). If the SQL tail is fast but PostgREST p99 is high, the stall is pool wait, lock wait, or serialisation, not the query. The managed-service console exposes equivalent latency charts; confirm it is showing p99 (not p95 or average) over a matching window before assuming a discrepancy.

​

Known limitations / FAQs

​

Tracked live in Vortex IQ Nerve Centre