Kill Task

Overview

Kill an active task. By default, kill is graceful: the task enters stopping, ingest stops, and already-submitted renders are allowed to finish before terminal shutdown. Send {"wait_for_renders": false} in the request body for immediate termination. Only tasks with scheduled, queued, running, ready, or stopping status can be killed. Terminal tasks (stopped, error, failed, completed, cancelled) return a failure response. Killing a scheduled task (an HLS pull created with scheduled_start_at whose worker has not launched yet) cancels it: the task becomes cancelled, no worker is ever started, and nothing is billed. wait_for_renders has no effect in that case.

Path Parameters

Parameter	Type	Required	Description
`task_id`	string	Yes	The ID of the task to kill

Request Body Parameters

Parameter	Type	Required	Description
`wait_for_renders`	boolean	No	Default: `true`. When `true`, kill is graceful (`running`/`ready` -> `stopping` -> terminal `stopped` once in-flight renders finish). When `false`, task is stopped immediately.

Example Request (Default Graceful Kill)

curl -X POST "https://api.narrative-sports.com/v1/tasks/YOUR_TASK_ID/kill" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response (Graceful Kill Accepted)

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "status": "Task stopping - waiting for current renders to finish",
  "instance_terminated": false
}

Example Request (Immediate Kill)

curl -X POST "https://api.narrative-sports.com/v1/tasks/YOUR_TASK_ID/kill" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wait_for_renders": false
  }'

Example Response (Immediate Kill)

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "status": "Task stopped",
  "instance_terminated": true
}

Response Fields

Field	Type	Description
`success`	string	Result status: `success` or `failure`
`task_id`	string	The task ID that was killed
`status`	string	Human-readable status message
`instance_terminated`	boolean	Whether the worker was successfully terminated

Example Response (Scheduled Task Cancelled)

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "status": "Task cancelled before its scheduled start",
  "instance_terminated": false
}

Response Examples

Already stopping (idempotent graceful kill)

{
  "success": "success",
  "task_id": "YOUR_TASK_ID",
  "status": "Task is already stopping",
  "instance_terminated": false
}

Worker termination failed

If the worker could not be terminated, the API returns a 500 error. The task remains active and continues to count against your concurrent task limit. The worker will automatically shut down when its maximum lifetime is exceeded.

{
  "detail": "Failed to terminate worker. The worker will automatically shut down when its maximum lifetime is exceeded."
}

Task not found or not owned by caller

{
  "success": "failure",
  "task_id": "YOUR_TASK_ID",
  "status": "Task not found",
  "instance_terminated": false
}

Task already stopped

{
  "success": "failure",
  "task_id": "YOUR_TASK_ID",
  "status": "Task is already stopped",
  "instance_terminated": false
}

Notes

Default behavior is graceful (wait_for_renders=true): kill requests transition active tasks into stopping and drain already-submitted renders.
Immediate behavior (wait_for_renders=false) hard-stops the worker and may interrupt in-progress processing.
For queued tasks, kill stops immediately (there is no render queue to drain yet).
If worker termination fails in immediate mode, the API returns a 500 error and the task remains active until automatic shutdown.

Overview

Task Creation

Task Management

License Usage

Deprecated

Highlights

Highlight Packages (Early Beta)

Recaps

Overview

Path Parameters

Request Body Parameters

Example Request (Default Graceful Kill)

Example Response (Graceful Kill Accepted)

Example Request (Immediate Kill)

Example Response (Immediate Kill)

Response Fields

Example Response (Scheduled Task Cancelled)

Response Examples

Already stopping (idempotent graceful kill)

Worker termination failed

Task not found or not owned by caller

Task already stopped

Notes

​Overview

​Path Parameters

​Request Body Parameters

​Example Request (Default Graceful Kill)

​Example Response (Graceful Kill Accepted)

​Example Request (Immediate Kill)

​Example Response (Immediate Kill)

​Response Fields

​Example Response (Scheduled Task Cancelled)

​Response Examples

​Already stopping (idempotent graceful kill)

​Worker termination failed

​Task not found or not owned by caller

​Task already stopped

​Notes

Overview

Path Parameters

Request Body Parameters

Example Request (Default Graceful Kill)

Example Response (Graceful Kill Accepted)

Example Request (Immediate Kill)

Example Response (Immediate Kill)

Response Fields

Example Response (Scheduled Task Cancelled)

Response Examples

Already stopping (idempotent graceful kill)

Worker termination failed

Task not found or not owned by caller

Task already stopped

Notes