Get Highlight

Overview

Retrieve metadata for a specific highlight by its ID. Returns the highlight’s event metadata and OTIO edit data — but does not return a signed video URL. Highlights are created whenever an event is detected, regardless of whether video rendering is enabled. To download the rendered video (only available when render_videos.render_video was set to ffmpeg), use GET /highlights/{highlight_id}/signed-url.

Request

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

Path Parameters

Parameter	Type	Description
`highlight_id`	string	The highlight ID (from the list highlights endpoint)

Response

{
  "highlight": {
    "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
  }
}

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.

Response Fields

Field	Type	Description
`highlight`	object	Highlight metadata object

Highlight Fields

Field	Type	Description
`id`	string	Unique highlight ID
`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 (soccer) or fighter (MMA) 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/fighters 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

Consumers should use the otio_crop field to distinguish landscape from portrait records.MMA highlights may additionally have a 1:1 square variant available (same fighter-tracking trajectory as the 9:16 portrait, wider crop window). The square variant is exposed only as a downloadable URL — fetch it via Get Signed URL with ?variant=1_1 or inspect the signed_square_urls map on Batch Signed URLs. It does not produce a separate metadata record.

Errors

Status	Description
`401`	Invalid or missing API key
`404`	Highlight not found, or does not belong to the authenticated customer

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Request

Path Parameters

Response

Response Fields

Highlight Fields

Portrait Crop Duplicate Records

Errors

​Overview

​Request

​Path Parameters

​Response

​Response Fields

​Highlight Fields

​Portrait Crop Duplicate Records

​Errors

Overview

Request

Path Parameters

Response

Response Fields

Highlight Fields

Portrait Crop Duplicate Records

Errors