PPLX-36 - trckr

← PPLX-36

feature,backend

Created: 2025-12-21 • Updated: 2025-12-22

Relationships Loading...

Add endpoint for per-query usage details with pagination and filtering.

## Implementation
- Create /api/usage/breakdown endpoint in backend/routers/usage.py
- Return paginated list of usage entries with query details
- Support filtering (date, model, thread) and sorting (cost, date, tokens)
- Include: query_text, model, tokens, cost, timestamp

## Response Schema
```json
{
  "items": [
    {
      "query_id": "...",
      "query_text": "What is the capital of France?",
      "model": "sonar",
      "prompt_tokens": 7,
      "completion_tokens": 147,
      "total_tokens": 154,
      "estimated_cost_usd": 0.0000154,
      "logged_at": "2025-12-21T06:35:29Z"
    }
  ],
  "total": 13,
  "page": 1,
  "page_size": 20
}
```

## Files to Create/Modify
- backend/routers/usage.py (add breakdown endpoint)
- backend/crud.py (add paginated query function)
- backend/schemas.py (add UsageBreakdownResponse)

## Acceptance Criteria
- GET /api/usage/breakdown returns paginated results
- Filtering by date/model/thread works
- Sorting by cost/date/tokens works (sort param)
- Pagination works correctly (page, page_size params)
- Query text truncated if too long
- Proper error handling

Pull Requests (comma-separated URLs)

Attachments

Comments (1)

agent · 2025-12-22

Implementation verified complete. ## Summary The /api/usage/breakdown endpoint was already fully implemented in this codebase as part of PPLX-44. ## Implementation Details ### Files Involved: - **backend/routers/usage.py:116-235** - GET /api/usage/breakdown endpoint with full parameter handling - **backend/schemas.py:353-373** - UsageBreakdownEntry and UsageBreakdownResponse schemas - **backend/crud.py:830-945** - get_usage_breakdown() function with filtering, sorting, pagination ### Features Verified: 1. **Pagination**: page and page_size params (1-100 per page) 2. **Sorting**: sort_by (date/cost/tokens) and sort_order (asc/desc) 3. **Filtering**: start_date, end_date, model, thread_id 4. **Query text truncation**: Limited to 100 chars (crud.py:929) 5. **Error handling**: 400 for invalid date range, 404 for missing thread ### Test Results: - 35 tests in test_usage.py - all passing - 414 total tests - all passing - Tests cover: pagination, sorting by all fields, filtering by all criteria, edge cases, error handling