# Query Metric Trendline

`GET /api/v1/data/metrics/trendline`

Retrieves a day-by-day series of aggregated values for a metric over a date range. Same access rules as Query Metric Value. Requires the `read` ability.

For competition metrics (`competition:*`) the series is a running-total curve, not per-day amounts: each point rolls up the latest known standing, as of that day, of every in-scope location that has one. The series is truncated to the competition's window regardless of the requested range, and carries one point per bucket end — every day by default, the last digested day of each week or month when grouped (grouping is available on the MCP tool, not this endpoint). When the range resolves a standing (the same condition under which Query Metric Value returns a value), the response names the resolved competition and its window in a top-level `competition` field, alongside `data`.

## 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 series to a single location. |

## Example request

```bash
curl "https://app.franchisesee.com/api/v1/data/metrics/trendline?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": [
        {
            "date": "2026-06-01",
            "value": 6142.18
        }
    ],
    "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."
        ]
    }
}
```
