> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.video/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Highlights Task

> Poll highlight generation task status and retrieve results

## GET /api/v1/sports/highlights/{task_id}

Poll the status of a highlight generation task and retrieve results when complete.

### Path Parameters

| Parameter | Type   | Required | Description                                  |
| --------- | ------ | -------- | -------------------------------------------- |
| task\_id  | string | Yes      | The task ID returned from the create request |

### Response

| Field         | Description                                                    |
| ------------- | -------------------------------------------------------------- |
| task\_id      | Task identifier                                                |
| status        | Current status: `pending`, `processing`, `completed`, `failed` |
| progress      | Progress percentage (0-100)                                    |
| created\_at   | When the task was created                                      |
| completed\_at | When the task completed (if finished)                          |
| result        | Highlight video details (when status=completed)                |
| error         | Error details (when status=failed)                             |

### Example Request

```bash theme={null}
curl https://api.usenarrative.ai/api/v1/sports/highlights/task_def456xyz
```

### Example Response (Processing)

```json theme={null}
{
  "task_id": "task_def456xyz",
  "status": "processing",
  "progress": 67,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "result": null,
  "error": null
}
```

### Example Response (Completed)

```json theme={null}
{
  "task_id": "task_def456xyz",
  "status": "completed",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:40:00Z",
  "result": {
    "video_url": "https://cdn.usenarrative.ai/highlights/video_abc123.mp4",
    "original_duration_sec": 7200,
    "edited_duration_sec": 900
  },
  "error": null
}
```

### Example Response (Failed)

```json theme={null}
{
  "task_id": "task_def456xyz",
  "status": "failed",
  "progress": 12,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:31:00Z",
  "result": null,
  "error": {
    "code": "PROCESSING_FAILED",
    "message": "Failed to process video: unsupported codec"
  }
}
```

### Result Fields

| Field                   | Description                                    |
| ----------------------- | ---------------------------------------------- |
| video\_url              | CDN URL to highlight reel (valid for 24 hours) |
| original\_duration\_sec | Duration of input video in seconds             |
| edited\_duration\_sec   | Duration of highlight reel in seconds          |

### Polling Strategy

Highlight generation typically takes 5-10 minutes for a 2-hour video.

Recommended polling intervals:

* First 2 minutes: every 10 seconds
* After 2 minutes: every 30 seconds
* After 10 minutes: every 60 seconds

### Notes

* Processing time varies based on video length
* Output video URL is valid for 24 hours
* Typical reduction: \~85% (2 hours → 15 minutes of highlights)


## OpenAPI

````yaml GET /api/v1/sports/highlights/{task_id}
openapi: 3.0.3
info:
  title: Sports API
  description: >-
    Sports video analysis and highlight generation API with async task
    processing
  version: 1.0.0
servers:
  - url: https://api.usenarrative.ai
    description: Production
security: []
paths:
  /api/v1/sports/highlights/{task_id}:
    get:
      tags:
        - Highlights
      summary: Get Highlights Task
      description: >-
        Poll the status of a highlight generation task and retrieve results when
        complete.
      operationId: getHighlightsTask
      parameters:
        - name: task_id
          in: path
          required: true
          description: The task ID returned from the create request
          schema:
            type: string
      responses:
        '200':
          description: Task status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HighlightsTaskResponse'
        '404':
          description: Task not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    HighlightsTaskResponse:
      type: object
      properties:
        task_id:
          type: string
          description: Task identifier
          example: task_abc123xyz
        status:
          type: string
          enum:
            - pending
            - processing
            - completed
            - failed
          description: Current task status
          example: completed
        progress:
          type: integer
          description: Progress percentage (0-100)
          minimum: 0
          maximum: 100
          example: 100
        created_at:
          type: string
          format: date-time
          description: When the task was created
        completed_at:
          type: string
          format: date-time
          description: When the task completed (if finished)
        result:
          $ref: '#/components/schemas/HighlightsResult'
        error:
          $ref: '#/components/schemas/TaskError'
      required:
        - task_id
        - status
        - progress
        - created_at
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
    HighlightsResult:
      type: object
      properties:
        video_url:
          type: string
          format: uri
          description: CDN URL to the generated highlight reel (valid for 24 hours)
        original_duration_sec:
          type: number
          description: Duration of the original video in seconds
        edited_duration_sec:
          type: number
          description: Duration of the highlight reel in seconds
    TaskError:
      type: object
      properties:
        code:
          type: string
          description: Error code
          example: PROCESSING_FAILED
        message:
          type: string
          description: Human-readable error message
          example: 'Failed to process video: invalid format'

````