# Prior authorization metrics for a payer

URL: https://docs.healthcare.dev/reference/payers/prior-authorization-metrics-for-a-payer

```http
GET https://api.healthcare.dev/v1/payers/{id}/prior-auth-metrics
```

Builder plan and up (Free: a few preview calls a month, then 403 `plan-upgrade-required`). The prior authorization metrics a payer posted for a year (default: the latest it posted), one report per reporting unit: percent of standard and expedited requests approved and denied, percent approved after appeal, percent approved after the review time was extended, and the mean and median time from request to decision (in hours; `as_reported` keeps the payer's own wording). Each metric carries the count and the total it is out of when the payer gives them, and what that total is (`denominator_basis`); a metric the payer doesn't give is `null` with a `not_reported_reason`, never estimated. Each report says how its values were read (`derivation`: `source_stated` when read directly from the posting, `reviewed` when a person checked them), links the posting (`evidence`) and the payer's list of items needing prior authorization when it gives one. A posting we couldn't read reliably yet is `report_status: pending_review`. Values are as the payer reported them in its annual public posting under the CMS Interoperability and Prior Authorization rule (CMS-0057-F). They are not audited by healthcare.dev or CMS, and payers count and round differently: compare with care and check the payer's posting (evidence).

Requires an API key: `Authorization: Bearer hdev_live_...`. See [Authentication](/authentication).

## Path parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `id` | string | yes | Payer id from `GET /v1/payers` | `humana` |

## Query parameters

| Name | Type | Required | Description | Example |
| --- | --- | --- | --- | --- |
| `year` | integer | no | Calendar year the metrics cover (default: the latest posted) | `2025` |
| `unit` | string | no | Only this reporting unit: its key or id (e.g. a contract `H1036`, `FL-MEDICAID`) | `H1036` |
| `view` | "compact" \| "standard" \| "full" | no | How much of each record to return (default `full`). `compact`: `unit`, `year`, `report_status`, `standard`, `expedited` (fewest tokens, for agents). `standard`: every field except `payer_id`, `payer_name`. `full`: every field. | `compact` |
| `fields` | string | no | Comma-separated fields to return instead of a view. Valid fields: `payer_id`, `payer_name`, `unit`, `year`, `report_status`, `standard`, `expedited`, `all_requests`, `items_requiring_pa_url`, `confidence`, `derivation`, `evidence`, `as_of`. | `unit,year,report_status` |

## Examples

**curl**

```sh
curl "https://api.healthcare.dev/v1/payers/humana/prior-auth-metrics" \
  -H "Authorization: Bearer $HDEV_API_KEY"
```

**TypeScript**

```ts
const res = await fetch("https://api.healthcare.dev/v1/payers/humana/prior-auth-metrics", {
  headers: { Authorization: `Bearer ${process.env.HDEV_API_KEY}` },
});
const { data, meta } = await res.json();
```

**Python**

```python
import os
import requests

res = requests.get("https://api.healthcare.dev/v1/payers/humana/prior-auth-metrics", headers={"Authorization": f"Bearer {os.environ['HDEV_API_KEY']}"})
body = res.json()
```

## Response

The payer's reports for the year

```json
{
  "data": {
    "payer": {
      "id": "string",
      "name": "string"
    },
    "year": 1,
    "years_available": [
      1
    ],
    "note": "string",
    "reports": [
      {
        "payer_id": "string",
        "payer_name": "string",
        "unit": null,
        "year": 1,
        "report_status": "available",
        "standard": {
          "approved": null,
          "denied": null,
          "approved_after_appeal": null,
          "approved_after_extension": null,
          "mean_time": null,
          "median_time": null
        },
        "expedited": {
          "approved": null,
          "denied": null,
          "approved_after_appeal": null,
          "approved_after_extension": null,
          "mean_time": null,
          "median_time": null
        },
        "all_requests": {
          "approved_after_extension": null
        },
        "items_requiring_pa_url": "string",
        "confidence": 0,
        "derivation": null,
        "evidence": [
          null
        ],
        "as_of": "2026-10-24T12:00:00Z"
      }
    ]
  },
  "meta": {
    "source": "cms-icd10",
    "data_version": "2026.1",
    "retrieved_at": "2026-10-24T12:00:00Z",
    "license": "Public domain (CMS). Reference data, not medical advice."
  },
  "links": {
    "self": "/v1/payers/humana/prior-auth-metrics",
    "next": null
  }
}
```

### Fields

| Field | Type | Always present | Description |
| --- | --- | --- | --- |
| `payer` | object | yes |  |
| `year` | integer \| null | yes | The year shown: `year` if given, else the latest with a posting; null with none |
| `years_available` | integer[] | yes | Years with postings, newest first |
| `note` | string | yes | How to read these values (show it with them) |
| `reports` | PriorAuthMetricsReport[] | yes | One per reporting unit, by unit key |

## Errors

Errors are `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)). Branch on `type`, not on `title`. See [Errors](/errors).

| Status | `type` | When |
| --- | --- | --- |
| 400 | `invalid-request` | A parameter or the body failed validation; `errors` lists each field. |
| 401 | `unauthorized` | Missing, malformed or revoked API key. |
| 403 | `plan-upgrade-required` | The plan doesn't include this feature; `required_plan` names the plan that does. |
| 404 | `not-found` | No record with that id (retired records are still returned). |
| 429 | `rate-limited / quota-exceeded` | Too many requests per second (retry after `Retry-After`), or the monthly quota is used up. |
| 503 | `dataset-unavailable / unavailable` | The dataset has no published version yet, or the service is degraded. |