# Get Leaderboard

`GET /api/v1/data/leaderboard`

Retrieves a ranked leaderboard of locations for a single metric over a period. Franchisor-scoped tokens only (franchisee tokens receive 403). Requires the `read` ability.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `period` | string | yes |  |
| `metric` | string | yes | Metric key, e.g. `net_sales_amount`, `custom:loyalty_signups`, or `competition:spring_challenge`. Competition metrics rank locations by their current cumulative standing in the latest competition for that metric; the requested period does not change the competition window. |
| `source` | string | no |  |
| `district_id` | string | no |  |
| `district_id_2` | string | no |  |
| `location_category_id` | string | no |  |
| `state` | string | no |  |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/data/leaderboard?period=current&metric=string" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"
```

## Responses

### 200 Success

```json
{
    "data": {
        "period": "last_week",
        "metric": "net_sales_amount",
        "source": null,
        "starts_on": "2026-11-02",
        "ends_on": "2026-11-08",
        "num_locations": 48,
        "closed_location_count": 0,
        "total": 1268430.55,
        "median": 25890.12,
        "mean": 26425.64,
        "benchmark_stats": {
            "prior": {
                "total": 1221875.1,
                "median": 25102.44,
                "mean": 25455.73,
                "location_count": 48,
                "closed_location_count": 0
            },
            "yoy": {
                "total": 1221875.1,
                "median": 25102.44,
                "mean": 25455.73,
                "location_count": 48,
                "closed_location_count": 0
            }
        },
        "locations": [
            {
                "location_id": "9b1c8f3e-7a2d-4c5b-8e1a-2f3d4c5b6a7e",
                "name": "Downtown Austin",
                "value": 41285.9,
                "rank": 1,
                "benchmarks": {
                    "prior": {
                        "previous_value": 39870.25,
                        "previous_rank": 2,
                        "previous_on": "Oct 26 – Nov 1, 2026",
                        "rank_change": -1,
                        "value_change": 1415.65,
                        "value_change_rate": 0.0355
                    },
                    "yoy": {
                        "previous_value": 39870.25,
                        "previous_rank": 2,
                        "previous_on": "Oct 26 – Nov 1, 2026",
                        "rank_change": -1,
                        "value_change": 1415.65,
                        "value_change_rate": 0.0355
                    }
                }
            }
        ]
    }
}
```

### 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."
}
```
