Skip to main content
Reader is a dependency like any other. You want to know when it’s slow, failing, or costing more than you budgeted. This guide covers the minimum set of metrics worth tracking and how to pull them.

Metrics to track

Pulling data from Reader

Usage history

GET /v1/usage/history returns recent requests with per-row proxyMode, credits, status, and duration. Paginate through and feed into whatever your observability stack is (Datadog, Grafana, a local Postgres, a spreadsheet).

Credits balance

A one-call poll:
Scrape this on an interval (every minute or two is plenty) and graph it.

Instrumenting client calls

Wrap your reader.read calls in a metrics helper:

Alerts worth having

  • Error rate > 5% over a 5-minute window → investigate
  • Credit balance < 20% of limit → notify ops
  • p95 latency doubles → slowdown or site blocking spike
  • rate_limited count > 10 per minute → need to upgrade or throttle
  • Webhook failedDeliveries rising → your listener is broken
Don’t alert on single-request failures. Reader will occasionally see target-site timeouts and that’s normal.

Request ID correlation

Every response (success or error) carries an x-request-id header. Log it on every call. When something goes wrong, include the request ID in your bug report. Reader’s server-side logs key off that ID and we can reconstruct what happened.

Dashboard shortcut

The Reader dashboard shows most of these metrics without any instrumentation. Check there first for ad-hoc investigations; build your own tracking for alerts and long-term capacity planning.

Next