Delete Tasks

Delete one or more scheduled or failed tasks

Endpoint

POST https://api.ugc.inc/tasks/delete

Overview

Delete one or more tasks from your task queue. This is useful for removing tasks that are no longer needed or clearing failed tasks that you don’t want to retry.

Important Restrictions:

• You can only delete tasks with status scheduled or failed
• Tasks with other statuses (pending, complete) cannot be deleted using this endpoint
• Deletion is permanent and cannot be undone

Request Body

taskIds · string[] · required

Array of task IDs to delete

All tasks must belong to your organization and must have status scheduled or failed

Response

data · object

Deletion result information

Show Result properties

deleted · number

Number of tasks successfully deleted

ids · string[]

Array of deleted task IDs

Error Cases

• 400 Bad Request: Attempting to delete tasks that are not in scheduled or failed status
• 404 Not Found: Some tasks don’t exist or don’t belong to your organization
• 400 Bad Request: No task IDs provided

cURL

curl -X POST https://api.ugc.inc/tasks/delete \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskIds": ["task_abc123", "task_def456"]
  }'

Success Response

{
  "ok": true,
  "code": 200,
  "message": "Successfully deleted 2 task(s)",
  "data": {
    "deleted": 2,
    "ids": [
      "task_abc123",
      "task_def456"
    ]
  }
}

When to Delete Tasks

Consider deleting tasks in these scenarios:

1. Scheduled tasks no longer needed - Plans changed, account was removed, etc.
2. Failed tasks you don’t want to retry - Task configuration was incorrect
3. Cleanup after testing - Remove test tasks from your queue
4. Bulk task management - Clear out old or irrelevant tasks

Deletion is permanent!

Once a task is deleted, it cannot be recovered. Make sure you really want to delete the task before calling this endpoint.

Best Practices

Check task status before deleting:

Always verify that tasks are in scheduled or failed status before attempting to delete them. Use the Get Tasks endpoint to check task statuses first.

1. Fetch tasks

   Use the Get Tasks endpoint to retrieve tasks and check their status

2. Filter eligible tasks

   Filter out tasks with status scheduled or failed

3. Confirm deletion

   Ensure you want to permanently delete these tasks

4. Delete tasks

   Call the delete endpoint with the filtered task IDs

Example: Cleanup Failed Tasks

// Get all tasks
const tasksResponse = await client.tasks.getTasks();

if (tasksResponse.ok) {
  // Filter tasks that failed and are older than 7 days
  const oldFailedTasks = tasksResponse.data.filter(task => {
    if (task.status !== 'failed') return false;
    
    const taskDate = new Date(task.created_at);
    const weekAgo = new Date();
    weekAgo.setDate(weekAgo.getDate() - 7);
    
    return taskDate < weekAgo;
  });
  
  if (oldFailedTasks.length > 0) {
    console.log(`Found ${oldFailedTasks.length} old failed tasks`);
    
    // Confirm with user (in a real app)
    const confirmed = confirm(
      `Delete ${oldFailedTasks.length} old failed tasks?`
    );
    
    if (confirmed) {
      const deleteResponse = await client.tasks.deleteTasks({
        taskIds: oldFailedTasks.map(t => t.id)
      });
      
      if (deleteResponse.ok) {
        console.log(`Deleted ${deleteResponse.data.deleted} tasks`);
      }
    }
  }
}

Example: Cancel Scheduled Task

// You scheduled a warmup task but need to cancel it
const taskId = 'task_xyz789';

// First check the task status
const tasksResponse = await client.tasks.getTasks();

if (tasksResponse.ok) {
  const task = tasksResponse.data.find(t => t.id === taskId);
  
  if (task && task.status === 'scheduled') {
    // Task is scheduled and can be deleted
    const deleteResponse = await client.tasks.deleteTasks({
      taskIds: [taskId]
    });
    
    if (deleteResponse.ok) {
      console.log('Task cancelled successfully');
    }
  } else if (task && task.status === 'pending') {
    console.log('Task is already running, cannot delete');
  } else if (task && task.status === 'complete') {
    console.log('Task already completed, cannot delete');
  }
}

Cannot Delete Running or Completed Tasks

Status restrictions:

• pending tasks (currently running) cannot be deleted
• complete tasks cannot be deleted

Only scheduled (not yet started) and failed tasks can be deleted.

If you need to cancel a running task, you’ll need to wait for it to complete or fail. There is no way to interrupt a task that is currently executing.

Comparison with Retry

Action	Delete	Retry
Purpose	Permanently remove task	Re-execute failed task
Allowed statuses	scheduled, failed	failed only
Reversible?	No	No (but task runs again)
Use when	Don’t need the task	Want to try again