---
title: "Create Run"
method: POST
path: "/runs"
---

# Create Run

`POST /runs`

## Request

- Base URL: `https://www.clipzyn.com/v1`
- URL: `https://www.clipzyn.com/v1/runs`
- Auth: HTTP bearer

Create one queued run and return {run_id, status, eta_sec, options_effective}.

options_effective.resolved_order is the authoritative per-format count and
request-compiler activation echo for the accepted run.

THIS CALL SPENDS QUOTA when a new run is accepted. Call GET /v1/account first, send one
Idempotency-Key per intended run, then poll GET /v1/runs/{run_id}/progress first at
eta_sec and at most once every 60 to 120 seconds. Recover from quota_exceeded through
POST /v1/billing/checkout; for concurrency_limited or daily_limit, wait retry_after_sec
before retrying. Fix validation_error, source_invalid, or feature_not_entitled before a
new attempt.

## Request body

- RunRequest: POST /v1/runs body (v2 §4.2). Exactly one of storage_path | source_url | sources. No ``force`` (admin-only, never on /v1), no ``video`` (dev local-path), no ``re_run_id`` (deferred, A6): the /v1 grammar is narrower than the browser's on purpose.
  - `storage_path` string, nullable
  - `source_url` string, nullable
  - `sources` SourceInput[], nullable
    - `role` string, nullable
    - `media_kind` string, nullable
    - `origin` string, required
    - `filename` string, required
    - `storage_key` string, nullable
    - `source_url` string, nullable
    - `size_bytes` integer, nullable
    - `subject_hint` string, nullable
  - `top_n` integer
  - `sub_clips` boolean
  - `shorts` boolean
  - `midform` boolean
  - `midform_n` integer, nullable
  - `midform_request` string, nullable
  - `trailer` boolean
  - `trailer_request` string, nullable
  - `twitter` boolean
  - `twitter_n` integer, nullable
  - `twitter_request` string, nullable
  - `carousels` boolean
  - `carousels_n` integer, nullable
  - `carousels_request` string, nullable
  - `clip_request` string, nullable
  - `count_mode` 'exact' | 'engine', nullable
  - `engine` 'standard' | 'deep', nullable: The cut to run: 'standard' (the normal cut) or 'deep' (the deep cut). Omit it for the default routing. 'deep' is refused with validation_error while the deep cut is switched off. Echoed as options_effective.engine.
  - `title` string, nullable
  - `host_name` string, nullable
  - `guest_name` string, nullable
  - `source_type` string
  - `duration_sec` number, nullable
  - `pulse_recorded_at` string, nullable
  - `pulse_go_live_at` string, nullable
  - `pulse_people` PulsePerson[], nullable
    - `name` string, required
    - `role` string, nullable
    - `note` string, nullable
  - `pulse_episode_context` string, nullable
  - `pulse_focus_topics` string[], nullable
  - `pulse_avoid_topics` string[], nullable
  - `pulse_source_published_at` string, nullable

## Response `201`

Successful Response

- RunResponse: POST /v1/runs 201 body.
  - `run_id` string, required
  - `status` string, required
  - `eta_sec` integer, nullable
  - `options_effective` OptionsEffective, required
  - `deprecation_notice` string, nullable

## Other responses

- `422`: Validation Error

---

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