Skip to main content
POST
/
batch
/
jobs
/
{batch_job_id}
/
cancel
Cancel Batch Job
curl --request POST \
  --url https://api.talkifai.dev/batch/jobs/{batch_job_id}/cancel \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "Scheduled job cancelled successfully",
  "batchJobId": "<string>",
  "redisJobCancelled": true,
  "contactsCancelled": 123
}

​
Overview

Cancels a batch job permanently. Behavior depends on job status:
  • Scheduled: Cancels Redis scheduled job + updates database
  • Pending/Running: Marks remaining contacts as cancelled
  • Completed/Failed/Cancelled: Returns error (cannot cancel)
Running calls complete normally; only pending/queued contacts are cancelled.

​
Request

POST /batch/jobs/{batch_job_id}/cancel

​
Path Parameters

ParameterTypeRequiredDescription
batch_job_idstring✅Unique batch job identifier

​
Response

{
  "success": true,
  "message": "Scheduled job cancelled successfully",
  "batchJobId": "batch_xyz789",
  "redisJobCancelled": true,
  "contactsCancelled": 58
}

​
Response Fields

FieldTypeDescription
successbooleanWhether cancellation succeeded
messagestringCancellation result description
batchJobIdstringCancelled batch job ID
redisJobCancelledbooleanWhether Redis scheduled job was cancelled
contactsCancelledintegerNumber of contacts marked as cancelled

​
Examples

​
Example 1: Cancel Scheduled Job

curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "message": "Scheduled job cancelled successfully",
  "batchJobId": "batch_xyz789",
  "redisJobCancelled": true,
  "contactsCancelled": 100
}

​
Example 2: Cancel Running Job

curl -X POST "https://api.talkifai.com/batch/jobs/batch_abc123/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "message": "Job was already running - cancelled remaining contacts",
  "batchJobId": "batch_abc123",
  "redisJobCancelled": false,
  "contactsCancelled": 42
}

​
Example 3: Cancel Already Completed Job (Error)

curl -X POST "https://api.talkifai.com/batch/jobs/batch_completed/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "detail": "Cannot cancel job in 'completed' status"
}

​
Behavior by Status

Job StatusCancellation Behavior
scheduledCancels Redis defer job + marks DB as cancelled
pendingMarks all contacts as cancelled
runningMarks remaining (non-terminal) contacts as cancelled
completed❌ Error: Cannot cancel completed job
failed❌ Error: Cannot cancel failed job
cancelled❌ Error: Already cancelled

​
Contact Statuses Affected

When cancelling a running job, only contacts in non-terminal statuses are cancelled: Cancelled Statuses:
  • pending — Not yet called
  • queued — Waiting for retry
  • no_answer — Will be retried
  • busy — Will be retried
  • timeout — Will be retried
Not Affected (Terminal Statuses):
  • completed — Already successful
  • failed — Final failure
  • blocked — Permanently blocked
  • invalid_number — Invalid phone number
  • carrier_error — Carrier error (final)
  • cancelled — Already cancelled

​
Error Handling

​
404 Not Found

{
  "detail": "Batch job not found"
}

​
400 Bad Request

{
  "detail": "Cannot cancel job in 'completed' status"
}
Error CodeCause
job_not_foundBatch job ID doesn’t exist
already_terminalJob is in completed/failed/cancelled status

​
500 Internal Server Error

{
  "detail": "Failed to cancel batch job"
}

​
Use Cases

​
Cancel Due to Error in Campaign

If you discover an error in your campaign (wrong message, wrong numbers): 
# Immediately cancel the job
curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Cancel Scheduled Job Before Start Time

# Job scheduled for 9 AM, but you want to cancel at 8 AM
curl -X POST "https://api.talkifai.com/batch/jobs/batch_scheduled/cancel" \
  -H "Authorization: Bearer YOUR_API_KEY"

Authorizations

​
Authorization
string
header
required

Your TalkifAI API key. Get it from Studio → Settings → API Keys.

Path Parameters

​
batch_job_id
string
required

Response

Batch job cancelled

​
success
boolean
Example:

true

​
message
string
Example:

"Scheduled job cancelled successfully"

​
batchJobId
string
​
redisJobCancelled
boolean
​
contactsCancelled
integer