---
title: "GET /model-hub/eval-templates/<id>/usage/"
method: GET
path: "/model-hub/eval-templates/{template_id}/usage/"
tags: ["model-hub"]
---

# GET /model-hub/eval-templates/<id>/usage/

`GET /model-hub/eval-templates/{template_id}/usage/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/model-hub/eval-templates/{template_id}/usage/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

Returns usage stats, chart data, and the paginated usage table.
Query params: page (0-based), page_size, period
(30m|6h|1d|7d|30d|90d|180d|365d), optional start_date/end_date pair
(overrides period — sent by the FE for Today / Yesterday / Custom).

The response is rendered through
``EvalUsageStatsResponseResultSerializer(instance=...).data`` at the
boundary so shape drift surfaces here instead of shipping silently.

Counts and lists only successful runs from the usage ledger
(``APICallLog`` rows with status ``success``), from every source: tasks,
playground, composites, datasets and experiments. Errored and skipped runs
are not usage but stay in the eval logs (task logs, template eval logs);
an in-flight run counts once it succeeds. ``error_count`` is therefore 0
and ``pass_rate`` 100 whenever there are runs; both remain for
compatibility.

## Query parameters

- `page` integer
- `page_size` integer
- `period` '30m' | '6h' | '1d' | '7d' | '30d' | '90d' | '180d' | '365d'
- `start_date` string, date-time
- `end_date` string, date-time
- `refresh` boolean

## Response `200`

OK

- EvalUsageStatsResponse
  - `status` boolean, required
  - `result` EvalUsageStatsResponseResult, required
    - `template_id` string, uuid, required
    - `is_composite` boolean, required
    - `completeness` 'complete' | 'degraded' | 'pending'
    - `unavailable_fields` string[]
    - `stats` EvalUsageStats, required
      - `total_runs` integer, required
      - `runs_period` integer, required
      - `success_count` integer, required: Deprecated compatibility field. Usage counts only successful runs, so this always equals runs_period.
      - `error_count` integer, required: Deprecated compatibility field. Usage counts only successful runs, so this is always 0; failed runs stay in the eval logs.
      - `pass_rate` number, required: Deprecated compatibility field. Usage counts only successful runs, so this is 100 when runs_period is above 0, otherwise 0.
    - `chart` EvalUsageChartPoint[], required
      - `timestamp` string, required
      - `calls` integer
      - `avg_latency_ms` integer
      - `avg_score` number, nullable
      - `pass_count` integer
      - `fail_count` integer
    - `table` EvalUsageTableRow[], required
      - `row_id` string, required
      - `score` EvalUsageNumberCell
        - `cell_value` number, nullable
      - `result` EvalUsageStringCell
        - `cell_value` string, nullable
      - `input` EvalUsageStringCell
        - `cell_value` string, nullable
      - `reason` EvalUsageStringCell
        - `cell_value` string, nullable
      - `source` EvalUsageStringCell
        - `cell_value` string, nullable
      - `version` EvalUsageStringCell
        - `cell_value` string, nullable
      - `feedback` EvalUsageFeedbackCell
        - `cell_value` EvalUsageFeedback, nullable
          - `id` string, uuid, required
          - `value` string, nullable
          - `explanation` string
          - `action_type` string
          - `created_at` string
          - `user` string
      - `created_at` EvalUsageStringCell
        - `cell_value` string, nullable
      - `status` EvalUsageStringCell
        - `cell_value` string, nullable
      - `warnings` EvalUsageWarningsCell
        - `cell_value` object[], nullable
      - `detail` EvalUsageLogItemDetail
        - `input_variables` object, nullable
        - `output` object, nullable
        - `warnings` string[]
        - `mappings` object, nullable
        - `model` object, nullable: String or JSON object.
        - `version_id` string, nullable
        - `version_number` integer, nullable
        - `children` string[]
        - `aggregation_function` string, nullable
        - `total_children` integer, nullable
        - `completed_children` integer, nullable
        - `failed_children` integer, nullable
      - `composite` boolean
      - `aggregate_pass` boolean, nullable
    - `logs` EvalUsagePagination, required
      - `total` integer, required
      - `page` integer, required
      - `page_size` integer, required
    - `query_complete` boolean
    - `query_status` 'complete' | 'degraded' | 'pending'
    - `query_sampled` boolean
    - `query_completed_at` string, date-time
    - `query_cached` boolean
    - `query_refresh_failed` boolean
    - `query_refreshing` boolean

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `500`: Internal Server Error
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)