# List Risk Findings

`GET /api/v1/risk/findings`

Risk Assessment flags: stores whose discount rate or $0-check rate is outside their usual range, each with the plain-sentence factors the Risk drill-down shows. By default returns unresolved findings (open or acknowledged), worst tier first and, within a tier, longest-running first. Requires the `read` ability, the Risk Assessment feature, and the `view risk assessment` permission; a franchisee token additionally needs risk to be visible to franchisees.

Franchisee tokens see only their own stores' findings, receive no `tier`, `peak_tier`, or `escalation` (every flag reads "Outside your usual range" in `tier_label`), and never receive network findings. The same report backs the `get-risk-findings` MCP tool.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `location` | string | no | Location UUID. Adds `latest_assessment` for each rate the account scores to the response. A franchisee token asking for a location outside its portfolio receives 403. |
| `metric` | string | no | One rate. `cash_share` is scored only where the account has cash share turned on; it is flagged when the store's cash share falls well below its own norm. |
| `status` | string | no | One status, or `any`. Default open and acknowledged. |
| `min_tier` | string | no | Findings at or above this tier. Ignored for franchisee tokens. |
| `opened_since` | string | no | Only findings opened on or after this date, formatted `YYYY-MM-DD`. |
| `include_network` | boolean | no | Franchisor tokens only: also return `network_findings`, where much of the network moved together. Ignored for franchisee tokens. |
| `limit` | integer | no | Maximum findings to return (1–100, default 25). |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/risk/findings" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"
```

## Responses

### 200 Success

```json
{
    "data": {
        "latest_assessed_on": "2026-11-11",
        "count": 1,
        "total": 3,
        "summary": {
            "findings": 3,
            "stores": 2,
            "by_metric": {
                "field": {
                    "label": "Discount rate",
                    "findings": 2,
                    "stores": 2,
                    "by_tier": {
                        "field": 1
                    }
                }
            },
            "by_tier": {
                "field": 1
            },
            "stores_on_both_metrics": {
                "count": 1,
                "stores": [
                    "string"
                ]
            }
        },
        "findings": [
            {
                "id": "0f7d3b9e-5a1c-4e8f-b2d6-7c4a9e1f3b85",
                "location": {
                    "uuid": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                    "name": "Downtown Austin",
                    "district": "Central Texas",
                    "category": "Inline"
                },
                "metric": "discount_rate",
                "metric_label": "Discount rate",
                "kind": "spike",
                "kind_label": "Spike",
                "tier": "elevated",
                "tier_label": "Elevated",
                "peak_tier": "elevated",
                "status": "explained",
                "status_label": "Explained",
                "opened_on": "2026-10-27",
                "last_seen_on": "2026-11-10",
                "closed_on": null,
                "weeks_open": 3,
                "escalation": {
                    "on": "2026-11-03",
                    "from": "watch",
                    "to": "elevated"
                },
                "acknowledged_by": null,
                "explanation": {
                    "reason": "approved_promotion",
                    "reason_label": "Approved promotion",
                    "note": "BOGO bowls weekend run by the local marketing co-op.",
                    "by": "Jordan Rivera",
                    "on": "2026-11-04",
                    "promotion_window": {
                        "name": "BOGO Bowls Weekend",
                        "starts_on": "2026-11-07",
                        "ends_on": "2026-11-09"
                    }
                },
                "factors": [
                    {
                        "key": "own_history",
                        "status": "hit",
                        "text": "Discount rate was 6.8% last week, against a usual 2.1% for this store."
                    }
                ]
            }
        ],
        "network_findings": [
            {
                "id": "2c8e4a6f-9b1d-4f3a-8e5c-1d7b3f9a5e26",
                "location": {},
                "metric": "zero_net_check_rate",
                "metric_label": "$0-check rate",
                "status": "open",
                "status_label": "Open",
                "opened_on": "2026-10-20",
                "last_seen_on": "2026-11-10",
                "closed_on": null,
                "window_starts_on": "2026-10-13",
                "breadth_pct": 41.7,
                "movers": 20,
                "eligible": 48,
                "network_rate_pct": 1.9,
                "explanation": {}
            }
        ],
        "latest_assessment": {
            "field": {
                "assessed_on": "2026-11-10",
                "rate_pct": 6.8,
                "usual_rate_pct": 2.1,
                "comparable_stores_rate_pct": 2.4,
                "comparable_store_count": 12,
                "checks": 1834,
                "flagged": true,
                "tier_label": "Elevated",
                "suppression": null,
                "suppression_label": null
            }
        }
    }
}
```

### 401 Authentication failed or missing.

```json
{
    "message": "Unauthenticated."
}
```

### 403 The token lacks the required ability or the caller is not permitted.

```json
{
    "message": "This API token does not have the 'create' ability."
}
```

### 422 Validation failed.

```json
{
    "message": "The selected metric is invalid.",
    "errors": {
        "metric": [
            "The selected metric is invalid."
        ]
    }
}
```
