Monitoring

Rates API uses GitHub Actions workflows to monitor the service. The workflows monitor uptime, data collection, and code quality.

Uptime Checks

The API Uptime Monitoring workflow starts every 15 minutes. It does these steps:

1. It installs the dependencies with Bun.
2. It runs apps/api/bin/uptime-check.ts. This script sends requests to the production API at https://www.ratesapi.nz/api/.
3. If one or more requests fail, the workflow fails.
4. If the workflow fails, it makes a GitHub issue with the failure details.

If the API returns HTTP 500, 502, 503, or 504, the script sends the request again. It does this a maximum of 3 times.

Monitored Endpoints

• The health endpoint
• The list endpoint and one detail endpoint for each category
• The time-series endpoint for each category, with no filter and with an institution or issuer filter
• The mortgage time series, with a date, with a date range, and with the termInMonths filter

The script does not check /openapi or /openapi.json.

Alerts

When a request fails, the workflow makes a GitHub issue with the title 🚨 API Endpoint(s) Down. The issue has the labels incident and high-priority. It mentions the owner of the repository, and it contains the output of the failed requests.

Necessary Permissions

permissions:
  issues: write
  contents: read

If your organization limits permissions, make sure that GitHub Actions can make issues. Also make sure that the incident and high-priority labels exist.

Data Collection

The Scheduled Rate Collection workflow targets minute 17 every four hours (UTC). This is a best-effort schedule, not a freshness guarantee: GitHub can delay or skip scheduled runs. It also starts on pushes to main and can be started manually.

1. A preparation job waits for the matching commit to deploy, verifies D1 access, and runs the optional freshness-column migration once.
2. Four independent jobs collect mortgages, personal loans, car loans and cards. At most two run concurrently; one failed job does not cancel its peers. Each writes only its own dataset.
3. Each job retains collection and browser-recovery reports, including on failure. Failed jobs can be rerun independently from GitHub Actions.

Tests run in CI and before deployment; they are not rerun as a prerequisite for scheduled collection. CI and collection pin the same Bun version. Production runs do not overlap. Each dataset write remains atomic, and earlier historical dates are not rewritten.

For a read-only rehearsal of the same four jobs, use Run workflow → dry_run. Preparation and publication are skipped, and collection steps receive no database credentials. Dry runs have a separate concurrency group so they do not hold up production.

A scraper saves a dataset only when the merged data changed. A failed source or product check leaves that institution's previous records in place. Other institutions, including those in the same category, can still update. The run exits with an error after it finishes the independent categories, so a failed workflow can include successful writes.

Partial updates do not advance the dataset's lastChecked in the health response. That field records the last complete successful collection. The health response's lastUpdated records the last data change, which can be a partial update. Read Data Freshness before using these fields in alerts.

Direct Source Checks

The Direct institution source checks workflow runs browser, parser and partial-publication tests for relevant pull requests. These tests use local fixtures and test services. They do not use the Browser Use cloud key or contact live institution sites. A failed test fails the check.

Use Run workflow to start a live source-health audit when needed. This manual audit runs after the tests pass and can incur Browser Use charges. The full audit fails if a source or coverage check fails. Selected-institution diagnostics report coverage separately. Both keep diagnostic reports as artifacts. It never writes to D1. A failed live source audit does not mean that the code checks failed.

Code Quality

These workflows start for pull requests and for pushes to main:

Workflow	Checks
CI	bun run check (Oxlint, Oxfmt, TypeScript through tsgo, docs type generation, and tests) and bun run build (the API dry run, the docs OpenNext build, and the web build)
Fallow	Static analysis of the code
React Doctor	React diagnostics for the changed files

GitHub code scanning also runs CodeQL analysis through its default setup. This analysis does not have a workflow file in the repository.

The Deploy to Cloudflare workflow starts on each push to main. It runs bun run check before it deploys.

Add Checks

• To monitor a new endpoint, add it to apps/api/bin/uptime-check.ts.
• If a docs route becomes important, add a check for it.
• If GitHub issues are not enough, add a notification channel.
• If old data is more important than endpoint uptime, add a limit for data age.