# Query Metric Value

`GET /api/v1/data/metrics/query`

Retrieves a single aggregated value (summed or averaged) for a metric over a date range. With `location_id`, the caller must have access to that location; without it, the value aggregates across all tenant locations and the token must be franchisor-scoped. Requires the `read` ability.

Competition metrics (`competition:*`) are point-in-time standings rather than range aggregates: the value is the cumulative standing as of `end_on` (clamped to the competition's end date), and `aggregation_method` is `point_in_time`. A network query rolls standings up per the metric's configured summability — summed for common-unit values (e.g. dollars raised), averaged for per-location rates. The competition resolved is the latest started, rankable competition for the metric whose window overlaps the requested range; `value` is null when no such competition overlaps the range or it has no data yet, and the response names the resolved competition and its window in a `competition` block so the figure stays attributable. Note this differs from Get Leaderboard, which always ranks the latest competition for the metric regardless of the requested period — for a historical range the two endpoints can resolve different competitions.

## Query parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `metric` | string | yes | Metric key, e.g. `net_sales_amount`, `custom:loyalty_signups`, or `competition:spring_challenge`. |
| `source` | string | no |  |
| `start_on` | string | yes | Start of the date range (inclusive), formatted `YYYY-MM-DD`. |
| `end_on` | string | yes | End of the date range (inclusive), formatted `YYYY-MM-DD`. Must be on or after start_on. |
| `location_id` | string | no | Location UUID to scope the value to a single location. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/data/metrics/query?metric=string&start_on=2026-11-12&end_on=2026-11-12" \
  -H "Authorization: Bearer $FRANCHISESEE_TOKEN" \
  -H "Accept: application/json"
```

## Responses

### 200 Success

```json
{
    "data": {
        "value": 184250.37,
        "aggregation_method": "sum",
        "competition": {
            "id": "d4f6a8c0-2e5b-4c7d-9f1a-6b3e8d0c2a54",
            "name": "Summer Smoothie Challenge",
            "starts_on": "2026-06-01",
            "ends_on": "2026-08-31"
        }
    }
}
```

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