> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Opportunities API: Ranked fixes by projected site lift

> List a brand's optimization opportunities grouped by best practice, with projected site-score lift and the affected pages behind each one.

## Overview

The Opportunities API answers "what should we fix first". Scrunch groups a brand's optimization findings by **best practice** — one row per type of problem — and projects how much the site score would move if that type were resolved.

Start with the by-type list to rank the work, then open one type to see the pages behind it.

***

## Endpoints

| Method | Path                                                   | Purpose                                                           |
| ------ | ------------------------------------------------------ | ----------------------------------------------------------------- |
| GET    | `/{brand_id}/opportunities/by-type`                    | Every opportunity type, with projected lift and page counts.      |
| GET    | `/{brand_id}/opportunities/by-type/{best_practice_id}` | One type's detail, plus a paginated window of its affected pages. |

Both require a bearer token with the `query` scope. See [Authentication](/getting-started/authentication).

***

## Example request

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/opportunities/by-type"
```

```bash theme={null}
curl -H "Authorization: Bearer $SCRUNCH_API_KEY" \
  "https://api.scrunchai.com/v1/1234/opportunities/by-type/heading-structure?state=pending&limit=50"
```

***

## Reading the fields

**`site_impact_pp` is percentage points of site score, not a percentage change.** A value of `2.4` means resolving that whole type is projected to move the site score by 2.4 points, not to improve it by 2.4%.

**Header counts and the page window are scoped differently.** On the detail endpoint, the per-state counts in the header describe the *entire* type across the brand. The `pages` array beneath them is one paginated window, filtered by `state` and sized by `limit`/`offset`. They will not match, and that is intended — don't compute a total by counting the array.

`state` accepts `all`, `pending`, `reviewed`, `staged`, and `deployed`, and filters only the page window.

<Note>
  For a brand using Site Optimization's page selection, counts and lift cover the enabled pages only. Two brands with identical sites can therefore report different totals.
</Note>


## Related topics

- [List Opportunity Types](/api-reference/opportunities/list-opportunity-types.md)
- [Get Opportunity Type Detail](/api-reference/opportunities/get-opportunity-type-detail.md)
- [Get Site Audit Score](/api-reference/audit-scores/get-site-audit-score.md)