# List stream group configs

Each config applies to every stream whose application and name match its rule.

Endpoint: GET /persist/stream-group-configs
Version: 2.0.0
Security: engineBasic

## Query parameters:

  - `application` (string)
    Only groups whose match rule names this Engine application.

## Response 200 fields (application/json):

  - `name` (string, required)
    The group's identity, and the base name of the file it is stored in. Immutable: a write that changes it is a 409, and the match rule can be rewritten without re-keying the group. default is reserved, and regex metacharacters are a 400 — the name doubles as a file name and would be silently rewritten.

  - `match` (object, required)
    Which streams are in this group.

  - `match.application` (string, required)

  - `match.stream_pattern` (string, required)
    Stream name or pattern (e.g. cam.*).

  - `match.priority` (integer)
    When several groups match, lower wins.

  - `config` (object)
    The config applied to every stream the match rule selects.

  - `config.active` (boolean)
    Whether analysis runs.

  - `config.detector` (object,null)
    The stream's analysis; absent inherits from the layer below, explicit null selects none.

  - `config.detector.type` (string, required)
    Detector subtype: scene, object, vlm, or synthetic.
    Enum: "scene", "object", "vlm", "synthetic"

  - `config.listeners` (object)
    Listeners, keyed by name. Each entry merges independently of the others.

  - `config.processing` (object)
    How frames are sampled and shipped to analysis; absent inherits from the layer below.

  - `config.processing.inference_fps` (integer)
    Frames per second sent to analysis; -1 matches the source rate. Default -1.

  - `config.processing.window_seconds` (number)
    Seconds per analysis window (scene/VLM/synthetic). Default 2.

  - `config.processing.video_height` (integer)
    Resize frames to this height; -1 matches source, 0 matches the model. Default 0.

  - `config.processing.grayscale` (boolean)
    Send frames in grayscale. Default false.

  - `config.processing.frame_source` (string)
    Capture frames via the transcoder or periodic frame grabs. Default transcoder, except the synthetic detector, which taps the source packets and defaults to grab.
    Enum: "transcoder", "grab"

  - `config.processing.grab_interval_seconds` (number)
    Frame-grab period when frame_source is grab. Default 1.

  - `config.processing.buffer_frames` (integer)
    Frames buffered awaiting processing. Sized from the incoming video by default.

  - `config.processing.auto_throttle` (boolean)
    Reduce inference_fps automatically when inference falls behind. Default off.

  - `config.processing.catch_up` (object,null)
    Scene/VLM — skip stale backlog to the live edge when inference lags.

  - `config.processing.catch_up.enabled` (boolean)
    Default true.

  - `config.processing.catch_up.max_behind_seconds` (number)
    Default is the buffer's own headroom.

  - `config.processing.rollup_interval_seconds` (number)
    How long detections are held for batch/rollup listener events. Default 2.

  - `config.processing.gpu_ids` (array,null)
    Pin VIS-side inference to these GPUs; null lets VIS balance.

  - `config.service` (object)
    Which Video Intelligence Service analyzes the stream; absent inherits from the layer below.

  - `config.service.url` (string)
    VIS WebSocket endpoint, e.g. ws://vis-host:5001/ws/stream/.

  - `config.service.api_key` (string,null)
    Never echoed by a read. On a write: absent or null keeps the stored value, an empty string clears it.

  - `config.service.model_idle_timeout_seconds` (integer,null)
    How long VIS keeps an idle model loaded.

  - `config.diagnostics` (object)
    Debug aids; absent inherits from the layer below.

  - `config.diagnostics.save_images` (boolean)
    Save captured frames to disk on the Engine host. Default false.

  - `config.diagnostics.timing_log_seconds` (integer)
    Seconds between timing-metric dumps; 0 disables. Default 0.

  - `config.diagnostics.max_logged_messages` (integer)
    Protocol messages logged; -1 all, 0 disabled. Default 20.

  - `etag` (string,null)
    This group's revision, to quote as If-Match on a write. Carried on the document so a client that listed stream group configs can write one without reading it again; a single-group read repeats it in the ETag header. Server-assigned and ignored on a write.

## Response default fields (application/problem+json):

  - `type` (string)
    URI identifying the problem type.

  - `title` (string, required)
    Short, human-readable summary of the problem type.

  - `status` (integer, required)
    The HTTP status code, repeated from the response line.

  - `detail` (string)
    Human-readable explanation specific to this occurrence.

  - `instance` (string)
    URI identifying this specific occurrence of the problem.