PrevIQ Docs
Open app

Prevalence

Query, summarize, and compare prevalence rollups.

The core of the API. Three endpoints cover paginated queries, syndrome-level summaries, and single-organism comparisons.

List prevalence rollups

GET /api/v1/prevalence

A paginated, sortable list of prevalence rows. This is the same data behind the Explore page.

Query parameters

  • syndrome — string — Restrict to one syndrome bucket (e.g. UTI).
  • vendor_id — string — Restrict to one laboratory.
  • organism — string — Restrict to one canonical organism.
  • panel — string — Restrict to one panel.
  • min_tested — integer, default: 0 — Drop rows with a tested count below this floor. Set 30 to hide Tier C, 100 for Tier A only.
  • tier — string — Comma-separated sample-size tier filter, e.g. A or A,B. Returns only rows in those tiers (applied in addition to min_tested). An unknown tier letter returns 400.
  • date_start — string (ISO date) — Start of a date window (YYYY-MM-DD). When set, prevalence is computed live from the records in the window instead of served from precomputed rollups, and meta.computed is "windowed".
  • date_end — string (ISO date) — End of the date window (inclusive).

Note

A date window must be scoped: supply a vendor_id or syndrome (at level=cross_vendor, a syndrome is required). Otherwise the request returns 400. Omitting both date params serves the fast precomputed rollups exactly as before.

To discover the available range, call GET /api/v1/prevalence/date-bounds (optional vendor_id / syndrome), which returns { "start", "end" }.

  • level — string, default: vendor — Grouping level: vendor, syndrome, or cross_vendor.
  • sort_by — string, default: prevalence_rate — One of prevalence_rate, tested, detected, organism, syndrome, panel, vendor_id.
  • order — string, default: desc — asc or desc.
  • limit — integer, default: 50 — Page size, 1–10000.
  • offset — integer, default: 0 — Pagination offset.

cURL

curl "https://api.previq.ospri.bio/api/v1/prevalence?syndrome=UTI&min_tested=100&sort_by=prevalence_rate&order=desc&limit=10"

Returns an Envelope<PrevalenceItem> — see Envelopes & errors for the full row shape.

Important

An unknown sort_by returns 400 Bad Request with the list of valid fields in detail.

Syndrome summary

GET /api/v1/prevalence/summary

Per-syndrome aggregate stats — the data behind the Dashboard's syndrome chart.

  • vendor_id — string — Optional. If provided, returns stats for one laboratory only; otherwise across all labs.

Each row includes:

Field Meaning
syndrome The syndrome bucket.
specimen_count_estimate Estimated specimens (sum of max tested per panel).
total_tested Organism-result cells tested.
total_detected Total detections.
overall_detection_rate total_detected / total_tested.
vendor_count Distinct labs contributing.
organism_count Distinct organisms.
panel_count Distinct panels.

cURL

curl "https://api.previq.ospri.bio/api/v1/prevalence/summary?vendor_id=AFC"

Compare an organism across syndromes

GET /api/v1/prevalence/compare

A cross-vendor breakdown for a single organism, one row per syndrome it appears in, ordered by prevalence (most clinically relevant first).

  • organism — string, required — The canonical organism name.

cURL

curl "https://api.previq.ospri.bio/api/v1/prevalence/compare?organism=Escherichia%20coli"

Each row carries syndrome, tested, detected, prevalence_rate, sample_size_tier, is_clinically_reportable, and the 95% CI bounds.

Tip

Use compare to answer "where does this organism actually show up?" — it pools across labs so a single small lab can't skew the picture.