List Highlights

Overview

Retrieve metadata for all highlights belonging to the authenticated customer. Returns highlight IDs, event metadata, and OTIO edit data — but does not return signed video URLs. Highlights are created whenever an event is detected, regardless of whether video rendering is enabled. Use this endpoint to browse or search your highlights. To download a rendered video (only available when render_videos.render_video was set to ffmpeg), pass the id from the response to GET /highlights/{highlight_id}/signed-url.

Request

curl -X GET "https://api.narrative-sports.com/v1/highlights?task_id=YOUR_TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`task_id`	string	No	Filter highlights to a specific task (resolved via the task’s project)

Response

{
  "highlights": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "event_type": "goal",
      "custom_category_name": null,
      "event_description": "Team A scores from a corner kick",
      "event_timestamp_seconds": 1234.5,
      "edit_length": 30.0,
      "inclusion_reasoning": "Clear goal scored from corner kick with celebration",
      "created_at": "2025-01-15T12:30:00Z",
      "otio_edit": {
        "OTIO_SCHEMA": "Timeline.1",
        "name": "event_000_goal"
      },
      "target_team": "Team A",
      "target_players": ["Messi"],
      "otio_crop": null,
      "fight_number": null,
      "round_number": null,
      "fight_name": null,
      "event_metadata": null
    }
  ],
  "total": 1
}

The four fields at the bottom (fight_number, round_number, fight_name, event_metadata) are populated only for MMA multi-fight streams. For soccer or single-fight MMA streams they are null. See Multi-Fight Cards for the full contract.

Example (MMA, multi-fight card)

{
  "highlights": [
    {
      "id": "e_abc999",
      "event_type": "tko",
      "custom_category_name": null,
      "event_description": "Villarreal lands a flurry of unanswered punches; the referee steps in at 3:17 of round 1.",
      "event_timestamp_seconds": 4199.3,
      "edit_length": 32.5,
      "inclusion_reasoning": "TKO finish with referee intervention and commentator confirmation.",
      "created_at": "2026-04-17T13:05:00Z",
      "otio_edit": {
        "OTIO_SCHEMA": "Timeline.1",
        "name": "event_000_tko"
      },
      "target_team": null,
      "target_players": ["Kevin Villarreal", "Kevin Arreola"],
      "otio_crop": null,
      "fight_number": 2,
      "round_number": 1,
      "fight_name": "Kevin Villarreal vs Kevin Arreola",
      "event_metadata": {
        "fight_number": 2,
        "round_number": 1,
        "fight_name": "Kevin Villarreal vs Kevin Arreola"
      }
    }
  ],
  "total": 1
}

Response Fields

Field	Type	Description
`highlights`	array	List of highlight metadata objects
`total`	integer	Total number of highlights returned

Highlight Fields

Field	Type	Description
`id`	string	Unique highlight ID (use with `/highlights/{id}/signed-url` to download)
`event_type`	string?	Event category (`goal`, `missed_opportunity`, `penalty`, etc.)
`custom_category_name`	string?	Custom name when `event_type` is `other`
`event_description`	string?	Human-readable description of the event
`event_timestamp_seconds`	float?	When the event occurred in the stream (seconds from start)
`edit_length`	float?	Duration of the highlight clip in seconds
`inclusion_reasoning`	string?	Why this event was included as a highlight
`created_at`	string?	ISO 8601 timestamp of when the highlight was created
`otio_edit`	object?	OTIO timeline data for this highlight. Current highlights generate this automatically. See OTIO Format.
`target_team`	string?	Name of the team or fighter this highlight is associated with. One of the names from `team_names` in the task configuration. `null` when team names were not provided, the event is neutral, or the team/fighter could not be determined.
`target_players`	string[]?	Names of the players involved in this highlight, as identified from the commentary. Empty array when no specific players are mentioned or the event is not player-specific.
`otio_crop`	object?	Portrait crop data for this highlight (only present on portrait edits). Contains the `Narrative_SmartCrop` effect data used for 9:16 cropping. See OTIO Format — Portrait Crop.
`fight_number`	integer?	MMA only. 1-based index of the fight within the stream. Null for soccer. See Multi-Fight Cards.
`round_number`	integer?	MMA only. 1-based round number scoped to this fight (resets each new fight). Null for walkouts, intros, inter-fight filler, and all non-MMA highlights.
`fight_name`	string?	MMA only. Human-readable fight label, e.g. `"Fighter A vs Fighter B"`. Falls back to `"Fight N"` when walkouts weren’t detected. Null for soccer.
`event_metadata`	object?	Raw sport-specific metadata blob. For MMA this mirrors `fight_number`/`round_number`/`fight_name` and may include forward-compatible fields. Use this if you want the full blob rather than the promoted columns.

Portrait Crop Duplicate Records

When a highlight has portrait crop data (i.e. both landscape and portrait were rendered), the API returns two records with the same id:

A landscape record with otio_crop: null
A portrait record with otio_crop populated containing the portrait crop anchor data

This means the highlights array may contain duplicate IDs. Consumers should group by id and use the otio_crop field to distinguish landscape from portrait records.MMA highlights may additionally have a 1:1 square variant. It’s exposed only as a downloadable URL (see Get Signed URL ?variant=1_1 or signed_square_urls on Batch Signed URLs); it does not add a third metadata record.

Errors

Status	Description
`401`	Invalid or missing API key
`500`	Server error

Typical Flow

Call GET /highlights to list all your highlights (optionally filter by task_id)
Inspect metadata fields (event_type, event_description, etc.)
Use id with GET /highlights/{highlight_id}/signed-url to download specific videos

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Query Parameters

Response

Example (MMA, multi-fight card)

Response Fields

Highlight Fields

Portrait Crop Duplicate Records

Errors

Typical Flow

​Overview

​Request

​Query Parameters

​Response

​Example (MMA, multi-fight card)

​Response Fields

​Highlight Fields

​Portrait Crop Duplicate Records

​Errors

​Typical Flow

Overview

Request

Query Parameters

Response

Example (MMA, multi-fight card)

Response Fields

Highlight Fields

Portrait Crop Duplicate Records

Errors

Typical Flow