---
title: "List derived facts for a media item, with quotes for what is missing"
method: GET
path: "/v1/media/{id}/facts"
tags: ["media"]
---

# List derived facts for a media item, with quotes for what is missing

`GET /v1/media/{id}/facts`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/media/{id}/facts`
- 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`

The enhancement menu. `facts` is everything expensive we have already computed about this source — subject tracks, mattes — with its status, a small summary a caller can act on without fetching the artifact, and `charge` (what it was billed; absent when it cost nothing, e.g. a matte produced as a side effect of a compose you already paid for, or one delivered below the behind-subject presence floor). `offers` is what is NOT present yet, with a real server quote. A matte is offered ONLY when you pass `startSec`+`endSec` — the clip's SOURCE window — because a matte's price is a function of its duration and a whole-source quote for a three-second clip is not a price. Pass the window from the editor and you get a per-clip matte quote plus the status of that window's matte; omit it from the library and you get everything except the matte.

## Path parameters

- `id` string, required

## Query parameters

- `kind` 'subjectTrack' | 'matte'
- `startSec` number
- `endSec` number

## Response `200`

Facts + offers.

- MediaFactsResponse: Facts and offers for a media item, plus an exact-window resolution when requested.
  - `facts` MediaFact[], required
    - `factId` string, required: The persisted fact receipt identity. Reuse pending or ready exact-window facts without dispatching new work.
    - `kind` 'transcript' | 'subjectTrack' | 'matte', required
    - `intent` object, required
      - `kind` 'whole' | 'window', required
      - `window` object: The SOURCE window this fact covers, when it is scoped to a clip.
        - `startSec` number, required
        - `endSec` number, required
    - `status` 'pending' | 'ready' | 'failed', required
    - `summary` object
      - `presenceFraction` number: Matte only: fraction of frames carrying a detected subject (0–1). Below 0.6 there is no reliable silhouette — the matte is delivered but cannot carry a behind-subject graphic, and is NOT charged.
      - `faceCount` number
      - `language` string
      - `wordCount` number
      - `durationSec` number
    - `charge` object: What this fact was BILLED, in USD. Absent when it cost nothing: a compose/render side effect (already paid for inside that operation) or an unusable matte.
      - `usd` number, required
    - `error` object
      - `code` string, required
      - `message` string, required
    - `readyAt` number
  - `offers` MediaFactOffer[], required: What is NOT yet present and could be bought. A `matte` offer appears ONLY when the request carried `startSec`+`endSec` (the clip's SOURCE window) — a matte's price is a function of its duration, so there is no honest whole-source matte quote. `transcript` is never offered: it is produced by the ingest pipeline, not bought here.
    - `kind` 'transcript' | 'subjectTrack' | 'matte', required
    - `quotedUsd` number, required: The server's price for this enhancement, in USD. Meaningful ONLY when `available` is true — an unavailable offer quotes 0 because there is nothing to price yet.
    - `available` boolean, required
    - `reason` string: Why this cannot be bought right now. Present iff `available` is false. e.g. `media_not_ready` (the source has no known duration yet).
  - `exact` union: The server-selected fact or offer for one exact source window. Present when kind, startSec, and endSec are supplied; clients consume this instead of recreating the fact hash.
    - object
      - `kind` 'subjectTrack' | 'matte', required
      - `scope` object, required
        - `startSec` number, required
        - `endSec` number, required
      - `state` 'pending' | 'ready' | 'failed', required
      - `fact` MediaFact, required: One derived fact about a media item — computed once, charged at most once.
        - `factId` string, required: The persisted fact receipt identity. Reuse pending or ready exact-window facts without dispatching new work.
        - `kind` 'transcript' | 'subjectTrack' | 'matte', required
        - `intent` object, required
          - `kind` 'whole' | 'window', required
          - `window` object: The SOURCE window this fact covers, when it is scoped to a clip.
            - `startSec` number, required
            - `endSec` number, required
        - `status` 'pending' | 'ready' | 'failed', required
        - `summary` object
          - `presenceFraction` number: Matte only: fraction of frames carrying a detected subject (0–1). Below 0.6 there is no reliable silhouette — the matte is delivered but cannot carry a behind-subject graphic, and is NOT charged.
          - `faceCount` number
          - `language` string
          - `wordCount` number
          - `durationSec` number
        - `charge` object: What this fact was BILLED, in USD. Absent when it cost nothing: a compose/render side effect (already paid for inside that operation) or an unusable matte.
          - `usd` number, required
        - `error` object
          - `code` string, required
          - `message` string, required
        - `readyAt` number
    - object
      - `kind` 'subjectTrack' | 'matte', required
      - `scope` object, required
        - `startSec` number, required
        - `endSec` number, required
      - `state` 'available' | 'unavailable', required
      - `offer` MediaFactOffer, required: A purchasable enhancement that this media item does not have yet.
        - `kind` 'transcript' | 'subjectTrack' | 'matte', required
        - `quotedUsd` number, required: The server's price for this enhancement, in USD. Meaningful ONLY when `available` is true — an unavailable offer quotes 0 because there is nothing to price yet.
        - `available` boolean, required
        - `reason` string: Why this cannot be bought right now. Present iff `available` is false. e.g. `media_not_ready` (the source has no known duration yet).

## 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.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

[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)