Skip to content
Docs
API reference / Metrics & Leaderboards

Query Metric Value

MD View as MarkdownPlain text version of this page
Open in ClaudeAsk questions about this page Open in ChatGPTAsk questions about this page
GET /api/v1/data/metrics/query

Token needs the read ability. About tokens

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

  • metric string required
    Metric key, e.g. net_sales_amount, custom:loyalty_signups, or competition:spring_challenge.
  • source Source
    google yelp store_audit ecosure smg meazureup decision_logic
  • start_on string (date) required
    Start of the date range (inclusive), formatted YYYY-MM-DD.
  • end_on string (date) required
    End of the date range (inclusive), formatted YYYY-MM-DD. Must be on or after start_on.
  • location_id string (uuid)
    Location UUID to scope the value to a single location.

Responses

    • data MetricQueryResult
      A single aggregated metric value; value and aggregation_method are null when there is no data.
      • value number required nullable
      • aggregation_method string required nullable
        sum average point_in_time
      • competition CompetitionAttribution
        The competition a served standing was read from. Present only for competition metrics (competition:*) when a value resolved, so the figure stays attributable when more than one competition has run on the metric.
        • id string (uuid) required
        • name string required
        • starts_on string (date) required
        • ends_on string (date) required
    • message string
    • message string
    • message string
    • errors object 
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"
Response 
{
    "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"
        }
    }
}