> ## Documentation Index
> Fetch the complete documentation index at: https://headgate.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List queues with backlog derivatives



## OpenAPI

````yaml /api/headgate.openapi.yaml get /queues
openapi: 3.1.0
info:
  title: headgate control API
  version: 0.1.0
  description: >
    The web UI is one client of this control API and gets no

    privileged access — asynqmon reads Redis directly, which is why its
    compatibility

    note is three minor versions stale.


    Both the Go and Rust implementations serve this spec, and the conformance
    suite

    asserts identical responses. Every list endpoint is bounded to prevent
    inspection

    from becoming an unbounded store operation: asynq's

    GetQueueInfo is O(number of groups) and has pinned Redis CPU for seconds in

    production. Monitoring caused the outage.


    DERIVED FROM THE ARCHITECTURE, NOT FROM A PREDECESSOR'S UI. The first draft
    of this

    spec was the asynq Inspector surface -- list by state, act on one job, pause
    a queue

    -- with new nouns bolted on. That inherited three problems: it omitted bulk

    operations, history, and enqueue (which asynq and apalis-board respectively
    DO have),

    and more importantly it had no endpoint for the question this system's own
    design

    creates. When dequeue is an admission decision, the operator's first
    question is not

    "what is in the queue" but "why is THIS job not running" -- see
    /jobs/{id}/admission.

    No predecessor needs that endpoint because no predecessor has a gate.
servers:
  - url: /api/v1
security: []
paths:
  /queues:
    get:
      summary: List queues with backlog derivatives
      responses:
        '200':
          description: Queue backlog and throughput summaries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueueStats'
components:
  schemas:
    QueueStats:
      type: object
      required:
        - queue
        - weight
        - unfinished_jobs
        - by_state
        - arrival_rate
        - drain_rate
        - paused
        - count_is_approximate
      properties:
        queue:
          type: string
        weight:
          type: integer
          minimum: 1
          description: >-
            Fleet-wide queue-selection weight; unrelated to per-job rate-budget
            weight.
        unfinished_jobs:
          type: integer
          minimum: 0
          description: >-
            Exact O(1) count of pending, scheduled, available, running, and
            retryable jobs.
        max_unfinished_jobs:
          type:
            - integer
            - 'null'
          minimum: 0
          description: >-
            Null disables producer backpressure; zero rejects all new unfinished
            work.
        by_state:
          type: object
          additionalProperties:
            type: integer
        arrival_rate:
          type: number
          description: jobs/sec over a 1m window
        drain_rate:
          type: number
        time_to_drain_ms:
          type:
            - integer
            - 'null'
          description: >-
            Null when arrival is greater than or equal to drain; alert on this
            condition rather than depth alone.
        oldest_available_ms:
          type:
            - integer
            - 'null'
          description: >-
            Store-clock age of the oldest available job; null when none is
            available.
        quiet_groups:
          $ref: '#/components/schemas/QuietGroupMetrics'
        paused:
          type: boolean
        memory_bytes:
          type:
            - integer
            - 'null'
          minimum: 0
          description: Last explicitly requested bounded sample; null until sampled.
        count_is_approximate:
          type: boolean
          description: >-
            True when a maintained bound was hit and the returned count is
            approximate.
    QuietGroupMetrics:
      type: object
      required:
        - arrival_rate
        - drain_rate
        - noisy_partitions
        - approximate
      description: Queue signals excluding partitions with disproportionate in-flight work.
      properties:
        arrival_rate:
          type: number
        drain_rate:
          type: number
        time_to_drain_ms:
          type:
            - integer
            - 'null'
        oldest_available_ms:
          type:
            - integer
            - 'null'
        noisy_partitions:
          type: integer
          minimum: 0
        approximate:
          type: boolean

````