---
title: "List switch (multicam) candidates + recommendation for a synced-angle group"
method: GET
path: "/v1/projects/{id}/selector/candidates"
tags: ["selector"]
---

# List switch (multicam) candidates + recommendation for a synced-angle group

`GET /v1/projects/{id}/selector/candidates`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/projects/{id}/selector/candidates`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`, scopes: `media:read`)
  - API key in header `PAYMENT-SIGNATURE`

Required permission: media:read

## Path parameters

- `id` string, required

## Query parameters

- `groupId` string, required

## Response `200`

Per-moment scored candidates + the recommended cut schedule + best-audio bed.

- SelectorCandidatesResponse: Selector (switch) candidates + recommendation for a synced-angle group. Every candidate carries score + contributions + reasons so the agent reweights from evidence; the recommendation is the lowered cut schedule + best-audio bed.
  - `projectId` string, required
  - `groupId` string, required
  - `selectorVersion` string, required
  - `signalVersions` object, required
  - `moments` SelectorMomentGroup[], required
    - `startSec` number, required: Span start (output seconds).
    - `endSec` number, required: Span end (output seconds).
    - `chosen` string, required: The recommended candidateId, or "__hold__" (abstain).
    - `pacingNote` string, nullable: Which mechanism produced the pick (argmax / hysteresis / override / hold …).
    - `candidates` SelectorScoredCandidate[], required
      - `candidateId` string, required: Stable angle/source id. An unknown id is rejected, never remapped.
      - `role` string, nullable: Agent-declared semantic tag (e.g. "wide", "webcam").
      - `score` number, required: The weighted prominence score (Σ weights·signal).
      - `contributions` object, required: signalKey → weighted contribution (the agent reweights from this).
      - `reasons` string[], required
  - `recommendation` object, required
    - `cutSchedule` SelectorCutSpan[], required
      - `startSec` number, required
      - `endSec` number, required
      - `candidateId` string, required
      - `sourceInSec` number, required: Chosen source window start (declared-offset resolved).
      - `sourceOutSec` number, required
      - `reasons` string[], required
    - `audioBed` SelectorAudioSpan[], required: Best-audio bed (instance #3): the clearest mic per span.
      - `startSec` number, required
      - `endSec` number, required
      - `candidateId` string, required: The chosen audio source (the clearest mic) for this span → programAudioSourceId.
      - `reasons` string[], required
    - `suppressedSwitches` object[], required: Switches the stabilizer suppressed (the anti-ping-pong audit).
      - `atSec` number, required
      - `wouldHaveBeenCandidateId` string, required
      - `byScore` number, required
      - `blockedBy` string, required
      - `releaseAtSec` number, nullable, required
  - `divergesFromComposition` boolean

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.

---

[API](https://skmtc.dev/cueframe/apis/cueframe-api.md) · [All operations](https://skmtc.dev/cueframe/apis/cueframe-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cueframe/apis/cueframe-api/revisions/8f9bfe362b4a?raw)