---
title: "Buy a derived fact (subject track or behind-subject matte)"
method: POST
path: "/v1/media/{id}/facts"
tags: ["media"]
---

# Buy a derived fact (subject track or behind-subject matte)

`POST /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:write`)
  - API key in header `PAYMENT-SIGNATURE`

Purchases one enhancement for this source. `matte` REQUIRES `intent:{startSec,endSec}` — the clip's SOURCE window — because a matte's cost scales with its duration. For `subjectTrack` the same `intent` is OPTIONAL: give the clip's source window to buy the track the render will look up for THAT clip (and pay only for its duration); omit it for the whole source. If the fact already exists (pending or ready) this returns it with `alreadyExisted:true` and charges nothing. Charging happens on DELIVERY, never here: a job that never lands is never billed.

## Path parameters

- `id` string, required

## Request body

- MediaFactPurchaseRequest: POST /media/:id/facts body.
  - `kind` 'subjectTrack' | 'matte', required: Which enhancement to buy. `transcript` is NOT purchasable here — it is delivered by the transcription pipeline.
  - `intent` object: The SOURCE window. REQUIRED for `matte` (its cost scales with duration). OPTIONAL for `subjectTrack`: give a clip's source window to buy the track the render looks up for THAT clip, and pay only for its duration; omit it to detect the whole source.
    - `startSec` number, required
    - `endSec` number, required

## Response `202`

Fact claimed (dispatched, or already present).

- MediaFactPurchaseResponse: POST /media/:id/facts response.
  - `factId` string, required
  - `status` 'pending' | 'ready' | 'failed', required
  - `quotedUsd` number, required
  - `alreadyExisted` boolean, required: True when this exact fact was already pending or ready. Nothing was dispatched and nothing will be charged.

## Other responses

- `400`: Bad request — validation_error / invalid_cursor / invalid_query.
- `401`: Missing or invalid Authorization header.
- `402`: Payment required — billing_required or x402 payment_*.
- `403`: Forbidden — permission insufficient.
- `404`: Resource not found.
- `409`: Conflict — stale_etag / idempotency_conflict / suggestions_already_complete.
- `422`: Unprocessable — invalid_composition / media_in_use / session_in_use / render_not_cancellable.
- `429`: Rate limited. Retry-After header present.
- `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)