info:
  name: Get Queue Statistics
  type: http
  seq: 9

http:
  method: GET
  url: '{{base_url}}/api/queue/stats'
  auth: inherit

docs: |-
  ## Get Queue Statistics

  Retrieves overall queue performance and status metrics.

  **Method:** GET

  **Endpoint:** /api/queue/stats

  **Authentication:** Required (Bearer token)

  **Query Parameters:**
  None (all stats returned)

  **Response:**
  - `overview` (object):
    - `total_items` (integer): All items in queue
    - `pending` (integer): Items awaiting processing
    - `processing` (integer): Items currently being processed
    - `completed` (integer): Successfully processed items
    - `failed` (integer): Failed items
  - `by_type` (object):
    - `progress` (object): Progress item counts
    - `note` (object): Note item counts
    - `highlight` (object): Highlight item counts
    - `bookmark` (object): Bookmark item counts
  - `by_status` (object):
    - `pending`: Count by type
    - `processing`: Count by type
    - `completed`: Count by type
    - `failed`: Count by type
  - `performance` (object):
    - `avg_processing_time_ms` (number): Average processing duration
    - `throughput_per_minute` (number): Items processed per minute
    - `success_rate` (number): Percentage of successful processing
    - `failure_rate` (number): Percentage of failures
  - `timing` (object):
    - `oldest_pending_age_seconds` (integer): Age of oldest pending item
    - `longest_processing_time_ms` (integer): Longest current processing time
    - `peak_queue_size_today` (integer): Maximum queue size today
  - `devices` (array): Top 5 devices by queue activity
    - `device_id` (string): Device UUID
    - `device_name` (string): Device name
    - `item_count` (integer): Items in queue from this device
  - `retention` (object):
    - `completed_items_30_days` (integer): Completed items in retention period
    - `purge_scheduled_at` (string): Next auto-purge time
  - `generated_at` (string): Statistics generation timestamp

  **Status Codes:**
  - 200: Success
  - 401: Unauthorized

  **Cache Behavior:**
  - Statistics cached for 60 seconds
  - Real-time data may vary slightly
  - Use `?refresh=true` to bypass cache

  **Use Cases:**
  - Monitor queue health
  - Identify performance bottlenecks
  - Track processing capacity
  - Alert on failures
  - Capacity planning
  - SLA monitoring
  - Dashboard metrics

  **Key Metrics to Watch:**
  - **Success Rate:** Should be >95%
  - **Avg Processing Time:** Depends on type
  - **Oldest Pending:** Should be <5 minutes
  - **Failed Items:** Investigate if >5%
  - **Throughput:** Baseline for capacity planning