> ## 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 Metadata Task

> Poll metadata extraction task status and retrieve results

## GET /api/v1/sports/extract-metadata/{task_id}

Poll the status of a metadata extraction 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        | Extracted metadata (when status=completed)                     |
| error         | Error details (when status=failed)                             |

### Example Request

```bash theme={null}
curl https://api.usenarrative.ai/api/v1/sports/extract-metadata/task_abc123xyz
```

### Example Response (Processing)

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

### Example Response (Completed)

```json theme={null}
{
  "task_id": "task_abc123xyz",
  "status": "completed",
  "progress": 100,
  "created_at": "2024-01-15T10:30:00Z",
  "completed_at": "2024-01-15T10:35:00Z",
  "result": {
    "events": [
      {
        "event_type": "play_start",
        "timestamp_sec": 125.5,
        "game_clock": "12:35",
        "home_score": 7,
        "away_score": 3
      },
      {
        "event_type": "score_change",
        "timestamp_sec": 892.4,
        "game_clock": "8:15",
        "home_score": 14,
        "away_score": 3
      }
    ],
    "metadata_url": "https://cdn.usenarrative.ai/metadata/events_abc123.json",
    "video_duration_sec": 7200,
    "events_detected": 142,
    "processing_stats": {
      "frames_processed": 108000,
      "processing_time_sec": 245.5,
      "fps": 30.0
    }
  },
  "error": null
}
```

### Example Response (Failed)

```json theme={null}
{
  "task_id": "task_abc123xyz",
  "status": "failed",
  "progress": 23,
  "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: invalid format"
  }
}
```

### Polling Strategy

Recommended polling intervals:

* First minute: every 5 seconds
* After 1 minute: every 15 seconds
* After 5 minutes: every 30 seconds

### Using Results with Highlights

The extracted metadata can be passed to the Generate Highlights endpoint for enhanced accuracy:

```bash theme={null}
# Download metadata
curl -o metadata.json "https://cdn.usenarrative.ai/metadata/events_abc123.json"

# Use with highlights generation
curl -X POST https://api.usenarrative.ai/api/v1/sports/highlights \
  -F "video=@game.mp4" \
  -F "metadata=@metadata.json"
```


## OpenAPI

````yaml GET /api/v1/sports/extract-metadata/{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/extract-metadata/{task_id}:
    get:
      tags:
        - Metadata Extraction
      summary: Get Metadata Task
      description: >-
        Poll the status of a metadata extraction task and retrieve results when
        complete.
      operationId: getExtractMetadataTask
      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/MetadataTaskResponse'
        '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:
    MetadataTaskResponse:
      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/MetadataResult'
        error:
          $ref: '#/components/schemas/TaskError'
      required:
        - task_id
        - status
        - progress
        - created_at
    Error:
      type: object
      properties:
        detail:
          type: string
          description: Error message
    MetadataResult:
      type: object
      properties:
        events:
          type: array
          items:
            type: object
          description: Array of extracted events matching the provided schema
        metadata_url:
          type: string
          format: uri
          description: URL to download the full metadata JSON file
        video_duration_sec:
          type: number
          description: Duration of processed video in seconds
        events_detected:
          type: integer
          description: Total number of events detected
        processing_stats:
          $ref: '#/components/schemas/ProcessingStats'
    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'
    ProcessingStats:
      type: object
      properties:
        frames_processed:
          type: integer
          description: Total frames analyzed
        processing_time_sec:
          type: number
          description: Time taken to process in seconds
        fps:
          type: number
          description: Source video frame rate

````