Create a run

Starts a run on an existing workflow or starts an analysis. The 202 response confirms acceptance, not completion.

• Access: an alpha-enabled API key with the RUN_WORKFLOWS permission. Workflow requests use a visible workflow_id. Analysis requests use completed, searchable source_ids visible to the workspace.
• Analysis input: send stored profile_id and stored report_template_id, plus formats and execution_profile_ref. You can pin each resource with its immutable version; when a version is omitted, the server resolves latest and records the resolved version in the run snapshot for reproducibility. Inline profiles and templates are not accepted on this endpoint. Use the rerender/report endpoint for a new presentation view.
• Workflow option: source_snapshot is an immutable object containing the selected video identifiers.
• Retries: send an Idempotency-Key. Reusing it with a different body returns 422.

Poll GET /api/v1alpha1/runs/{run_id} until the run finishes. Read analysis answers with GET /api/v1alpha1/runs/{run_id}/answers or workflow findings with GET /api/v1alpha1/findings?run_id={run_id}.

Header Parameters

Response Body

curl -X POST "https://example.com/api/v1alpha1/runs" \  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "execute_now": true,    "execution_profile_ref": "premium-analysis@1",    "formats": [      "json",      "markdown"    ],    "kind": "analysis",    "profile_id": "prof_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",    "profile_version": 1,    "report_template_id": "tpl_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",    "report_template_version": 1,    "source_ids": [      "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"    ]  }'

{  "analysis": {    "execution_profile_ref": "premium-analysis@1",    "locale": "ja",    "request_id": "0190b5d4-7e1f-7a2b-9c3d-1234567890ab",    "source_ids": [      "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"    ],    "sub_state": "accepted"  },  "created_at": "2026-08-21T09:00:00.000Z",  "id": "run_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",  "kind": "analysis",  "status": "queued",  "updated_at": "2026-08-21T09:00:00.000Z"}