List Tasks

Overview

Retrieve tasks belonging to the authenticated customer. Each task includes its ID, SRT URL, payload, whether it has been assigned (vs just warmed up), time remaining before auto-shutdown, and current status. Use the state query parameter to control which tasks are returned. If omitted, state=active is used.

Query Parameters

Name	Type	Required	Description
`state`	string	No	Task-state filter. Default: `active` (non-terminal tasks). Use `completed` for completed tasks only, `all` for all tasks, or any specific status: `scheduled`, `queued`, `running`, `ready`, `stopping`, `stopped`, `error`, `failed`, `completed`, `cancelled`.

Example Request

curl "https://api.narrative-sports.com/v1/tasks/list-tasks" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Requests with `state`

# Completed tasks only
curl "https://api.narrative-sports.com/v1/tasks/list-tasks?state=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

# All tasks for the account
curl "https://api.narrative-sports.com/v1/tasks/list-tasks?state=all" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": "success",
  "tasks": [
    {
      "task_id": "TASK_ID_1",
      "project_id": 1234,
      "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE_1",
      "task_payload": {
        "sport": "soccer",
        "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE_1",
        "srt_zero_relative_smpte_timecode": "01:00:00:00",
        "max_life_hours": 6.0
      },
      "assigned": true,
      "time_remaining_hours": 4.25,
      "task_status": "running"
    },
    {
      "task_id": "TASK_ID_2",
      "project_id": null,
      "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE_2",
      "task_payload": {
        "sport": "soccer",
        "srt_url": "srt://<host>:9000?passphrase=SRT_PASSPHRASE_2",
        "max_life_hours": 6.0
      },
      "assigned": false,
      "time_remaining_hours": 5.8,
      "task_status": "running"
    }
  ]
}

Response Fields

Field	Type	Description
`success`	string	Result status: `success` or `failure`
`tasks`	array	List of `TaskInfo` objects

TaskInfo Fields

Field	Type	Description
`task_id`	string	Unique task identifier
`project_id`	number \| null	Generated project ID for this stream task. Use this value when creating recaps or highlight packages. This may be `null` until the worker has linked the task to a project.
`srt_url`	string \| null	Worker-generated SRT ingest URL (per-task host + encryption passphrase). Stream to it verbatim.
`task_payload`	object	Full task configuration payload
`assigned`	boolean	`true` if the task has been assigned work via `/create-task` (or the deprecated `/assign-task`), `false` if only warmed up via the deprecated `/warmup` endpoint
`time_remaining_hours`	number \| null	Estimated hours before auto-shutdown, or `null` for terminal states. Measured from when the worker was launched; a `scheduled` task still has its full `max_life_hours` budget.
`task_status`	string	Current status: `scheduled`, `queued`, `running`, `ready`, `stopping`, `stopped`, `error`, `failed`, `completed`, or `cancelled`
`scheduled_start_at`	string \| null	For an `hls_pull` task created with `scheduled_start_at`: the expected stream start. `null` otherwise.

Notes

state=active returns non-terminal tasks only (default).
state=completed returns completed tasks only.
state=all returns all tasks for the account, including terminal tasks.
You can also filter by a specific status (scheduled, queued, running, ready, stopping, stopped, error, failed, completed, cancelled).
The assigned field distinguishes between tasks that have been fully assigned work (via /tasks/create-task, or the deprecated /tasks/assign-task) and tasks that were only pre-warmed via the deprecated /tasks/warmup endpoint without subsequent assignment.
time_remaining_hours is computed from max_life_hours and the task creation time. Use Extend Task Life to increase max_life_hours for an active task.

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Query Parameters

Example Request

Example Requests with `state`

Example Response

Response Fields

TaskInfo Fields

Notes

​Overview

​Query Parameters

​Example Request

​Example Requests with state

​Example Response

​Response Fields

​TaskInfo Fields

​Notes

Overview

Query Parameters

Example Request

Example Requests with `state`

Example Response

Response Fields

TaskInfo Fields

Notes