# Spooty Operations Snapshot

`GET /api/operations/snapshot` exposes backend-owned operational truth for Workspace and other clients.

The MVP reports truth Spooty already owns without a schema migration:

- track state from `TrackEntity.status`
- selected YouTube URL from `TrackEntity.youtubeUrl`
- selected YouTube candidate title, author, score, and reason from `TrackEntity`
- raw failure evidence from `TrackEntity.error`
- download retry count from `TrackEntity.downloadAttemptCount`
- rejected YouTube candidate explanations from `TrackEntity.rejectedYoutubeCandidatesJson`
- legacy rejected YouTube candidate URLs from `TrackEntity.rejectedYoutubeUrls`
- playlist and single-song counts from `PlaylistEntity.isTrack`
- queue depth and active jobs from BullMQ queues `track-search-processor` and `track-download-processor`
- Spotify connection presence from the stored Spotify user token

The endpoint intentionally does not infer candidate scoring history. Selected candidate metadata is persisted when Spooty chooses a candidate. Rejected candidate metadata is persisted when a selected candidate is rejected by manual retry or download failure. Older rows and URL-only cases fall back to rejected candidate objects containing only `url`.

Future persistence work is required for:

- full searched candidate history
- structured error class fields stored at write time instead of classified from the persisted raw error string
- operation attempt history across search and download phases
