Create Task

Overview

Create a processing task and launch a worker in a single request.

With the default source_type: "srt_listener", the endpoint blocks until the worker publishes an SRT URL (typically a few seconds).
With source_type: "hls_pull", Narrative pulls the supplied HLS manifest and returns immediately. There is no inbound SRT URL, so srt_url is null.
An hls_pull task can also be scheduled: pass scheduled_start_at and nothing is launched (or billed) right away. The task is stored with status scheduled, and Narrative starts the worker 15 minutes before that time so it is already pulling the manifest when the stream goes live. See Scheduling an HLS Pull.

This is the recommended way to start a task. The legacy Warmup + Assign Task flow is deprecated but still supported for backward compatibility.

Request Parameters

Parameter	Type	Required	Description
`sport`	string	Yes	Type of sport: `soccer`, `mma`, `baseball`, `american_football`, `squash`, `cheer`, `pickleball`, or `hockey`
`source_type`	string	No	Ingest mode: `srt_listener` (default) or `hls_pull`.
`source_url`	string	Conditional	HLS manifest URL. Required when `source_type` is `hls_pull`; omit for `srt_listener`.
`source_start`	object	No	Starting position for `hls_pull`. Omit to begin at the earliest retained segment, or select `live_edge`, `offset`, or `program_date_time` as described below. Invalid for `srt_listener`.
`scheduled_start_at`	string (date-time)	No	`hls_pull` only. Timezone-aware ISO-8601 time the stream is expected to start (e.g. `2026-09-05T19:00:00Z`). Must be in the future and within 30 days. The task is created with status `scheduled` and its worker launches 15 minutes before this time. Invalid for `srt_listener`.
`srt_zero_relative_smpte_timecode`	string	No	Starting SMPTE timecode for the stream (`HH:MM:SS:FF` or drop-frame `HH:MM:SS;FF`). Defaults to `"00:00:00:00"`. Used to interpret ingest timing; it is not automatically added to OTIO `start_time.value`.
`framerate`	string	No	Framerate in ffprobe rational format (e.g., `"30000/1001"`, `"30/1"`, `"25/1"`, `"60000/1001"`). Used both for interpreting the SMPTE timecode during SRT ingest and for any rendered videos/results returned by the API. If omitted the framerate is inferred from the stream, but this can be inconsistent — especially with VFR encoding. If provided, it is your responsibility to ensure the value is accurate.
`webhook_id`	string	No	Organization webhook endpoint ID. See the Webhooks Quickstart.
`render_videos`	object	No	Video rendering options
`team_names`	object	No	Team name metadata
`otio`	object	No	Optional OTIO metadata/timing override. OTIO edit generation is automatic; this object is not required to enable it. See OTIO Format.
`webhook_schema`	string	No	Deprecated — legacy OTIO field. Do not use for new integrations; OTIO edit generation is automatic.
`wh_schema_config`	object	No	Deprecated — legacy OTIO configuration paired with `webhook_schema="otio"`. Use `otio` only for metadata/timing overrides.
`max_life_hours`	number	No	Initial maximum instance lifetime in hours before automatic shutdown (default: 6). If a game runs long, use Extend Task Life to increase the limit up to 48 hours.
`name`	string	No	Optional project name for the task

Input Stream Requirements

For SRT listener tasks, stream to the returned URL. For HLS pull tasks, the manifest at source_url must remain reachable for the task duration. Both inputs must meet these media requirements:

Requirement	Details
Video + audio streams are required	SRT ingest expects both (`-map 0:v` and `-map 0:a`). Audio-less streams can fail ingest.
Commentary audio is required	Clear spoken commentary is required for detection. Commentary is not the same as having any audio stream; crowd/noise-only audio can ingest but won’t produce highlights.
Minimum bitrate for portrait cropping	Use at least 3000 kb/s source video bitrate for stable portrait crop quality.

See Video Input Requirements for validation commands and FFmpeg examples.

HLS Start Position

source_start controls where an HLS pull begins. The selected position becomes time 0 for the task’s transcript, detections, edits, and source archive.

Mode	Object	Behavior
Earliest retained (default)	Omit `source_start`	Starts at the first segment currently present in the manifest. This preserves the original HLS behavior.
Live edge	`{"mode":"live_edge"}`	Starts at the newest complete segment and processes new segments as they appear.
Stream offset	`{"mode":"offset","seconds":2640}`	Starts 2,640 seconds from the beginning of the currently retained HLS media timeline.
Program date-time	`{"mode":"program_date_time","timestamp":"2026-07-27T06:30:00Z"}`	Starts at the supplied timezone-aware wall-clock timestamp. The media playlist must contain `EXT-X-PROGRAM-DATE-TIME`, and the timestamp must still be retained.

For an EVENT or VOD playlist, offset 0 is normally the beginning of the event. For a sliding live playlist, offset 0 is the oldest segment still retained when the worker starts. Use program_date_time when a stable wall-clock position matters across a sliding DVR window. Requests outside the retained range fail instead of silently starting at a different point.

Scheduling an HLS Pull

Pass scheduled_start_at on an hls_pull request to create the task ahead of the event:

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "soccer",
    "source_type": "hls_pull",
    "source_url": "https://cdn.example.com/live/match/index.m3u8",
    "scheduled_start_at": "2026-09-05T19:00:00Z",
    "max_life_hours": 4,
    "name": "Saturday Match"
  }'

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "srt_url": null,
  "scheduled_start_at": "2026-09-05T19:00:00Z"
}

What happens next:

When	What
Immediately	The task is stored with `task_status: "scheduled"`. No worker runs and no usage accrues. The task does not count toward your concurrent task limit while it waits.
15 minutes before `scheduled_start_at`	Narrative launches the worker (status becomes `queued`, then `running`). `max_life_hours` and usage are measured from this launch, not from when the task was created. The worker begins pulling `source_url`; if the manifest is not live yet (for example it returns `403`/`404` or has no segments), the worker keeps retrying until 30 minutes after the scheduled start before failing the task.
Before launch	Cancel with Kill Task; the task becomes `cancelled` at no cost. Extend Task Life can raise the budget before or after launch.

If scheduled_start_at is less than 15 minutes away, the launch window is already open and the task starts immediately (status queued), exactly like an unscheduled hls_pull request; the response still echoes scheduled_start_at. If your organization is at its concurrent task limit when the launch time arrives, Narrative retries every few seconds and launches as soon as a slot frees. If no slot frees within 30 minutes of the scheduled start, the task is marked failed with a failure_reason explaining why.

Render Videos Object

Field	Type	Description
`render_video`	string	Rendering method: `ffmpeg` or `none` (use `none` to skip video output)
`retention_seconds`	integer	How long to retain rendered videos in seconds (default: 86400, min: 3600, max: 2592000 — approximately 1 month)

When render_video is set to "ffmpeg", rendered highlight clips are automatically uploaded to a project in your dashboard at app.narrative-sports.com. You can review, download, and manage your clips there. See Dashboard Integration for details.

Team Names Object

For soccer, baseball, and American football, use team names. For MMA and squash singles, use individual competitor names.

Field	Type	Description
`home_team_name`	string	Name of the home team, or the first fighter’s name for MMA
`away_team_name`	string	Name of the away team, or the second fighter’s name for MMA

Example Request

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "soccer",
    "srt_zero_relative_smpte_timecode": "01:00:00:00",
    "framerate": "30000/1001",
    "render_videos": {
      "render_video": "ffmpeg",
      "retention_seconds": 86400
    },
    "team_names": {
      "home_team_name": "Barcelona",
      "away_team_name": "Real Madrid"
    },
    "max_life_hours": 6,
    "name": "Champions League Final"
  }'

Example Response

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE"
}

HLS Pull Example

curl -X POST "https://api.narrative-sports.com/v1/tasks/create-task" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sport": "squash",
    "source_type": "hls_pull",
    "source_url": "https://cdn.example.com/live/match/index.m3u8",
    "source_start": {
      "mode": "offset",
      "seconds": 2640
    },
    "render_videos": {
      "render_video": "ffmpeg",
      "retention_seconds": 86400
    },
    "name": "Squash Final"
  }'

This example begins processing 44 minutes into the retained HLS timeline. Use {"mode":"live_edge"} instead when only newly published media should be processed. The response has the same shape, with srt_url: null:

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "srt_url": null
}

Response Fields

Field	Type	Description
`success`	string	Result status: `success` or `failure`
`task_id`	string	The created task ID
`srt_url`	string \| null	Complete SRT URL for an `srt_listener` task. `null` for `hls_pull`.
`scheduled_start_at`	string \| null	Echoes the requested start time for a scheduled `hls_pull` task; `null` otherwise.

The generated project ID is available from Get Task Info: call GET /v1/tasks/{task_id}/info and read task.project_id. The value may be null until the worker has linked the task to a project; retry after the task has started producing project data.

SRT Stream Configuration

URL Format

The srt_url includes everything needed to connect:

srt://<host>:9000?passphrase=<passphrase>

Parameter	Description
`<host>`	The per-task worker address that ingests your stream. Returned in the `srt_url`; valid only for this task.
`passphrase`	SRT encryption passphrase (the AES key for the connection).

Connect in SRT caller mode (the default for FFmpeg/OBS) over UDP 9000. SRT latency is negotiated automatically (the server uses 5 seconds); you may also set &latency=5000000 on your encoder.

Use the complete srt_url exactly as returned by the API. It contains the per-task host and encryption passphrase and is valid only for that task — don’t rebuild or modify it.

SMPTE Timecode

Provide srt_zero_relative_smpte_timecode in HH:MM:SS:FF (non-drop) or HH:MM:SS;FF (drop-frame) format. If framerate is provided, it is used to interpret the timecode. Otherwise, the framerate is inferred from the stream (note: inference can be inconsistent with VFR encoding). Drop-frame timecodes are only valid with 29.97 (30000/1001) or 59.94 (60000/1001) framerates; incompatible combinations cause the task to fail fast. For OTIO output, srt_zero_relative_smpte_timecode does not by itself shift source_range.start_time.value. Use otio.source_start_offset when you need a fixed frame offset in OTIO.

Task Lifecycle

create-task → queued → running → ready → running → completed
               ↓         ↓         ↓        ↓
             error    stopping  stopping   failed
                         ↓         ↓
                      stopped   stopped

create-task (scheduled_start_at) → scheduled ─(15 min before start)→ queued → …
                                       ↓
                                   cancelled (kill)

scheduled - hls_pull task with a future scheduled_start_at; no worker is running yet and nothing is billed
queued - Task created, worker launching
running - Worker active (booting or processing)
ready - SRT URL published, ready to receive stream
completed - Task finished successfully
error - Worker failed to launch (infrastructure / instance startup failure)
failed - Worker started but processing failed (pipeline / runtime error)
stopping - Graceful stop requested; ingest is stopping while already-submitted renders drain
stopped - Task was manually stopped via kill (immediate) or after stopping drain completes
cancelled - A scheduled task was killed before its worker launched

Error Handling

Rate Limits

Each account has a concurrent task limit. Narrative manages this limit centrally; organization members cannot change it through the API or dashboard. If you have no limit configured, the API returns 403:

{
  "detail": "Your account is not allowed to create tasks. Contact [email protected] to get started."
}

If you are at your limit, the API returns 429:

{
  "detail": "Concurrent task limit reached: 2/2. If you believe this is in error, or to request a rate limit increase, contact [email protected]."
}

Kill a running task or wait for one to finish before creating a new one.

Worker Launch Failure

If the worker fails to start (e.g., due to high traffic), the API returns a 500 error:

{
  "detail": "Failed to start worker due to high traffic. Please try again later."
}

Retry with a new create-task request after a short delay.

Worker Did Not Publish SRT URL in Time

If the worker takes too long to publish the SRT URL, the API returns 504:

{
  "detail": "Worker did not generate SRT URL in time. The task is still running — poll GET /tasks/{task_id}/status for readiness."
}

The task is still running in the background — poll Get Task Status or read srt_url from Get Task Info once the worker finishes booting.

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request Parameters

Input Stream Requirements

HLS Start Position

Scheduling an HLS Pull

Render Videos Object

Team Names Object

Example Request

Example Response

HLS Pull Example

Response Fields

SRT Stream Configuration

URL Format

SMPTE Timecode

Task Lifecycle

Error Handling

Rate Limits

Worker Launch Failure

Worker Did Not Publish SRT URL in Time

​Overview

​Request Parameters

​Input Stream Requirements

​HLS Start Position

​Scheduling an HLS Pull

​Render Videos Object

​Team Names Object

​Example Request

​Example Response

​HLS Pull Example

​Response Fields

​SRT Stream Configuration

​URL Format

​SMPTE Timecode

​Task Lifecycle

​Error Handling

​Rate Limits

​Worker Launch Failure

​Worker Did Not Publish SRT URL in Time

Overview

Request Parameters

Input Stream Requirements

HLS Start Position

Scheduling an HLS Pull

Render Videos Object

Team Names Object

Example Request

Example Response

HLS Pull Example

Response Fields

SRT Stream Configuration

URL Format

SMPTE Timecode

Task Lifecycle

Error Handling

Rate Limits

Worker Launch Failure

Worker Did Not Publish SRT URL in Time