> ## Documentation Index
> Fetch the complete documentation index at: https://dev-doc.dualmindlab.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /api/arena/model-stats

> Retrieve model performance statistics

## Authentication

**Required**: JWT Bearer token

## Response

<ResponseField name="items" type="array">
  Array of model statistics objects

  <Expandable title="Model statistics object">
    <ResponseField name="model_id" type="string">
      Model UUID
    </ResponseField>

    <ResponseField name="model_name" type="string">
      Model identifier (e.g., `llama-3.3-70b-versatile`)
    </ResponseField>

    <ResponseField name="display_name" type="string">
      Human-readable model name
    </ResponseField>

    <ResponseField name="provider" type="string">
      Provider name (`groq`, `bytez`, etc.)
    </ResponseField>

    <ResponseField name="total_votes" type="integer">
      Total number of votes received
    </ResponseField>

    <ResponseField name="wins" type="integer">
      Number of times voted as winner
    </ResponseField>

    <ResponseField name="losses" type="integer">
      Number of times voted as loser
    </ResponseField>

    <ResponseField name="ties" type="integer">
      Number of tie votes
    </ResponseField>

    <ResponseField name="win_rate" type="number">
      Win percentage (0.0 to 1.0)
    </ResponseField>

    <ResponseField name="elo_rating" type="number">
      Elo rating score (if implemented)
    </ResponseField>

    <ResponseField name="last_voted_at" type="string">
      ISO8601 UTC timestamp of most recent vote
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  curl -X GET 'http://localhost:5079/api/arena/model-stats' \
    -H 'Authorization: Bearer YOUR_JWT_TOKEN'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  const response = await fetch('http://localhost:5079/api/arena/model-stats', {
    headers: {
      'Authorization': `Bearer ${jwt}`
    }
  });

  const stats = await response.json();
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  import requests

  response = requests.get(
      'http://localhost:5079/api/arena/model-stats',
      headers={'Authorization': f'Bearer {jwt}'}
  )

  stats = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 Success theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "items": [
      {
        "model_id": "model-uuid-1",
        "model_name": "llama-3.3-70b-versatile",
        "display_name": "Llama 3.3 70B",
        "provider": "groq",
        "total_votes": 1523,
        "wins": 892,
        "losses": 431,
        "ties": 200,
        "win_rate": 0.585,
        "elo_rating": 1687,
        "last_voted_at": "2024-01-15T10:30:00.000Z"
      },
      {
        "model_id": "model-uuid-2",
        "model_name": "mixtral-8x7b-32768",
        "display_name": "Mixtral 8x7B",
        "provider": "groq",
        "total_votes": 1201,
        "wins": 645,
        "losses": 398,
        "ties": 158,
        "win_rate": 0.537,
        "elo_rating": 1542,
        "last_voted_at": "2024-01-15T09:15:00.000Z"
      }
    ]
  }
  ```

  ```json 401 Unauthorized theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "error": "Unauthorized"
  }
  ```

  ```json 500 STATS_ERROR theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
  {
    "success": false,
    "error": "Database query failed",
    "code": "STATS_ERROR"
  }
  ```
</ResponseExample>

## Side Effects

**Database Reads** (Line 88):

```csharp theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
var stats = await _modelStatsService.GetModelStatsAsync();
```

**Tables Read**:

* `ai_models` table: Model metadata
* `model_votes` table: Aggregated vote counts
* Potential JOIN with `comparisons` table (service-level)

**No Database Writes**: Read-only endpoint

**Query Characteristics**:

* Aggregation query (COUNT, SUM operations assumed)
* Potentially expensive for large vote datasets

## Authorization

**Authentication**: Required (JWT Bearer)

**Who Can Read**:

* Any authenticated user

**Data Visibility**:

* Global statistics (not user-specific)
* All users see same data

## Permissions

**No User Filtering**: Statistics global across all users

**No Privacy Controls**: All model performance data public to authenticated users

## Response Structure

**Ordering**: Not specified by API contract (implementation-defined)

* Ordering algorithm not enforced by server contract
* No explicit sort parameter in controller

**Pagination**: Not supported

* Returns ALL models
* Could cause performance issues if many models

**Filtering**: Not supported

* No query parameters for filtering by provider, win\_rate, etc.

## Edge Cases

1. **No votes exist**: Behavior not enforced by server contract (empty array likely)
2. **Model has zero votes**: Inclusion behavior not enforced by server contract
3. **Models without votes**: Inclusion behavior not enforced by server contract
4. **Inactive models**: Inclusion behavior not enforced by server contract
5. **Very large result set**: No pagination, performance not guaranteed

## Error Conditions

| Code          | HTTP | Cause                  | Controller Line |
| ------------- | ---- | ---------------------- | --------------- |
| N/A           | 401  | JWT missing or invalid | Middleware      |
| `STATS_ERROR` | 500  | Service exception      | 92-100          |

**Exception Handling** (Lines 92-100):

```csharp theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
catch (Exception ex) {
    return StatusCode(500, new { error = ex.Message, code = "STATS_ERROR" });
}
```

* All service exceptions return 500
* Exception message exposed to client

## Behavioral Guarantees

**Data Staleness**: Not specified by API contract

* Cache behavior implementation-defined and not guaranteed
* Real-time vs. cached not enforced by server contract

**Consistency**: Not guaranteed

* Votes in progress may not be reflected
* Consistency model not enforced by server contract

**Completeness**: Not specified by API contract

## Calculation Methods

**Win Rate** (service-level):

* Calculation formula not enforced by server contract
* Behavior when total\_votes = 0 not specified by API contract

**Elo Rating** (service-level):

* Calculation algorithm not documented in controller
* Null handling not enforced by server contract

**Ties/Losses Counting** (service-level):

* Vote counting logic not enforced by server contract
* Increment semantics implementation-defined and not guaranteed

## Performance Characteristics

**Query Complexity**: Depends on service implementation

* Simple aggregation: Fast
* Complex Elo calculation: Slower

**Index Requirements**:

* `model_votes.model_id` should be indexed
* `model_votes.created_at` for last\_voted\_at

**Response Size**: Unbounded (proportional to number of models)

**Caching**: Not enforced by server contract

* Cache behavior implementation-defined and not guaranteed
* Cache invalidation strategy not specified by API contract

## Use Cases

**Leaderboard Display**:

* Sort by win\_rate or elo\_rating
* Display top N models

**Model Selection**:

* Used by `GetTopperAndRandomModelAsync` for dual-chat topper mode
* Selects highest-rated model

**Analytics**:

* Track model performance over time
* Compare provider effectiveness

## Data Freshness

**Update Trigger**: Vote submission endpoint

* Stats updated when vote recorded
* Update timing not enforced by server contract (immediate vs. batch)

**Stale Data Risk**: Data freshness not enforced by server contract

**Real-Time Guarantee**: Not specified by API contract