Ask a question about a video (POST /v1/analyses). Provide video_id (video_…) and a free-text prompt like "Is there a person in this video?". Analysis runs asynchronously — use wait_for_analysis to block until done. The result contains answer (yes|no|indeterminate), confidence (0-1), clip timestamps, detected_count (count queries), and indeterminate_reason. Recommended: call validate_analysis first to confirm the prompt is assessable and preview the cost before spending credits. For 2–10 prompts on the same video, use create_analysis_batch (each prompt after the first is billed at 50%).

Run 2–10 prompts against the SAME video in one call (POST /v1/analyses/batch). Pricing: the first prompt is billed at full price, each additional prompt at 50% — always cheaper than separate create_analysis calls for multi-question workloads. Returns an analysis_batch with every analysis resource plus a pricing summary; poll each analysis id individually with get_analysis or wait_for_analysis. To check assessability of individual prompts first, use validate_analysis (free).

Register a video from a public https URL for analysis (POST /v1/videos, URL-ingest mode). The API fetches the video asynchronously — the returned video starts in status "processing" and becomes "ready". Supports video/mp4 and video/quicktime, max 2 GiB. Returns the video resource with its id (video_…).

Fetch an analysis by id (GET /v1/analyses/{id}). While running, shows live progress and queue_position. When status is "completed": result.answer (yes|no|indeterminate), result.confidence (for count queries this is confidence in the count itself), result.clips, result.detected_count (count-intent queries only; 0 = assessable but nothing found), result.indeterminate_reason (low_confidence — retry with a more specific prompt; nothing_detected — genuinely empty; unsupported_query_form — rephrase as yes/no or count; duration_mismatch — result untrusted), and result.video_duration_s (null when duration could not be determined). usage is {billed_seconds, credit_balance_after} — an immutable post-settlement snapshot.

Get the credit balance and transaction ledger for this API key (GET /v1/credits). Returns balance_seconds (the authoritative balance, in billable seconds), grant_seconds, used_seconds, and a paginated transaction list where each debit carries the analysis/stream id it came from (source_id, source_type). Use this to audit what each analysis cost, check the balance before a batch job, or diagnose an insufficient_credits error.

Get the stable test fixture (GET /v1/test-fixture): a video URL + prompt + expected answer for verifying an integration end-to-end without burning quota. Test-mode (pv_test_) keys return deterministic canned results.

Get credit balance and period usage meters for the current API key (GET /v1/usage). Use this after an insufficient_credits error to report the balance. For the per-analysis transaction ledger (what each analysis cost, with source ids), use get_credits instead.

List available analysis models (GET /v1/models) with status (stable | preview | deprecated) and capabilities. Use the model marked default:true unless you have a reason not to.

Dry-run a prompt WITHOUT creating an analysis or spending credits (POST /v1/analyses with validate_only: true). Compiles the prompt and returns an analysis_preview: the compiled query, assessable (false means the model cannot score this query form — rephrase as a yes/no or count question), estimated_seconds, and estimated_cost_usd (both null when the video duration is not yet known). Recommended before create_analysis to catch unassessable prompts and preview cost.

Block until an analysis reaches a terminal state (completed | failed | canceled), polling GET /v1/analyses/{id}. Returns { analysis, retry }: retry is null when the analysis reached a terminal state, or carries timeout guidance when the wait expired (call again). Default timeout 120s (test-mode analyses complete in seconds). On completion, see get_analysis for the full result field semantics (detected_count, indeterminate_reason, nullable video_duration_s, usage snapshot).