HHS APIocrportal.hhs.gov ↗
Access HIPAA breach reports under investigation by the HHS Office for Civil Rights. Retrieve breach records by organization, date, and affected individuals count.
What is the HHS API?
The HHS OCR Breach Portal API exposes 1 endpoint — list_breaches — that returns paginated records of HIPAA breach reports currently under investigation by the U.S. Department of Health and Human Services Office for Civil Rights. Each record covers breaches of unsecured protected health information affecting 500 or more individuals, with fields for organization name, submission date, breach size, and investigation status, ordered newest first.
curl -X GET 'https://api.parse.bot/scraper/8211c94f-4f38-42d4-b49d-0fe62d4b71a1/list_breaches?page=1' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace ocrportal-hhs-gov-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: HHS Breach Portal SDK — bounded, re-runnable; every call capped."""
from parse_apis.ocrportal_hhs_gov_api import HHSBreachPortal, ParseError
client = HHSBreachPortal()
# Fetch the most recent HIPAA breach reports to monitor for new entries.
for breach in client.breaches.list(limit=3):
print(breach.name_of_covered_entity, breach.state, breach.breach_submission_date, breach.individuals_affected)
# Get the single newest breach to check for new arrivals.
latest = client.breaches.list(limit=1).first()
if latest:
try:
print(latest.name_of_covered_entity, latest.type_of_breach, latest.location_of_breached_information)
except ParseError as e:
print(f"error: {e}")
print("exercised: breaches.list")
Fetch HIPAA breach reports currently under investigation by the Office for Civil Rights. Results are ordered by breach submission date (newest first). Each record represents a reported breach of unsecured protected health information affecting 500 or more individuals, reported within the last 24 months. Returns 100 records per page.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (1-based). Each page contains up to 100 records. |
{
"type": "object",
"fields": {
"page": "current page number",
"total": "total number of breach reports currently under investigation",
"breaches": "array of breach report records ordered by submission date descending",
"total_pages": "total number of pages available"
},
"sample": {
"data": {
"page": 1,
"total": 712,
"breaches": [
{
"state": "CO",
"type_of_breach": "Hacking/IT Incident",
"covered_entity_type": "Business Associate",
"individuals_affected": 602,
"breach_submission_date": "06/30/2026",
"name_of_covered_entity": "Virta Health",
"business_associate_present": "Yes",
"location_of_breached_information": "Network Server"
}
],
"total_pages": 8
},
"status": "success"
}
}About the HHS API
What the API Returns
The list_breaches endpoint returns an array of breach report records drawn from the HHS OCR Breach Portal, which publishes breaches of unsecured protected health information as required under the HITECH Act. Each response includes the total count of reports currently under investigation, total_pages for pagination, and the page currently being viewed. The breaches array contains individual records sorted by submission date descending — so the most recently reported incidents appear first.
Pagination and Coverage
Results are paged at up to 100 records per page. The page parameter (1-based integer) controls which page you retrieve. To walk the full dataset, check total_pages in any response and increment page until all records are fetched. This endpoint covers only breaches currently under active investigation by the Office for Civil Rights — breaches that have been resolved or archived are not included in these results.
Breach Record Fields
Each entry in the breaches array represents a single reported incident meeting the 500-individual threshold mandated by federal breach notification rules. Records include the covered entity's name, the type of covered entity (e.g., healthcare provider, health plan, business associate), the state, the number of individuals affected, the date of the breach, the date submitted, the type of breach (e.g., hacking/IT incident, unauthorized access), and the location of the breached information (e.g., network server, paper/film). These fields map directly to the data fields published on the public HHS portal.
The HHS API is a managed, monitored endpoint for ocrportal.hhs.gov — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when ocrportal.hhs.gov changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official ocrportal.hhs.gov API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track newly reported HIPAA breaches by fetching the first page of
list_breachessorted by submission date to surface incidents as they appear. - Aggregate breach counts by state using the state field across all pages to identify regional concentrations of incidents.
- Filter records by breach type (e.g., hacking/IT incident) to analyze trends in attack vectors against covered entities.
- Cross-reference breached organization names against a healthcare provider directory to assess compliance risk exposure.
- Monitor the total count of active investigations over time to measure regulatory enforcement activity.
- Identify which covered entity types (health plans, providers, business associates) are most frequently reported using the entity type field.
- Build a dataset of breach sizes by pulling the individuals-affected field across all pages to model population-level exposure.
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does HHS OCR have an official developer API for the Breach Portal?+
What does the `list_breaches` endpoint actually return, and how do I page through all records?+
breaches array of records ordered by submission date descending, along with page, total, and total_pages fields. Each page holds up to 100 records. Set the page parameter to 1, then increment it up to total_pages to retrieve the full dataset.Does the API include breaches that have already been resolved or closed by OCR?+
list_breaches covers only breaches currently under active investigation. Resolved or archived cases are not included. The HHS Breach Portal also maintains a separate "cases currently under investigation" view versus a closed-cases archive. You can fork this API on Parse and revise it to add an endpoint targeting the closed-cases data.Can I filter or search breaches by organization name, state, or breach type directly in the API?+
breaches array fields such as state, entity type, or breach type. You can fork this API on Parse and revise it to add server-side filtering parameters.