Skip to main content
POST
/
batch
/
jobs
/
{batch_job_id}
/
start
Start Batch Job Immediately
curl --request POST \
  --url https://api.talkifai.dev/batch/jobs/{batch_job_id}/start \
  --header 'Authorization: Bearer <token>'
{
  "success": true,
  "message": "Cancelled scheduled job, starting immediately",
  "batchJobId": "<string>",
  "status": "running",
  "contactsEnqueued": 123,
  "redisJobCancelled": true,
  "startedAt": "2023-11-07T05:31:56Z"
}

​
Overview

Starts a scheduled or pending batch job immediately, without waiting for the scheduled start time. Use cases:
  • Start a scheduled job ahead of time
  • Manually trigger a job that was created but not started
  • Override scheduling and begin processing now
Only works for jobs in scheduled or pending status. Running jobs cannot be started again.

​
Request

POST /batch/jobs/{batch_job_id}/start

​
Path Parameters

ParameterTypeRequiredDescription
batch_job_idstring✅Unique batch job identifier

​
Response

{
  "success": true,
  "message": "Cancelled scheduled job, starting immediately",
  "batchJobId": "batch_xyz789",
  "status": "running",
  "contactsEnqueued": 100,
  "redisJobCancelled": true,
  "startedAt": "2025-02-28T13:30:00Z"
}

​
Response Fields

FieldTypeDescription
successbooleanWhether start succeeded
messagestringStart result description
batchJobIdstringStarted batch job ID
statusstringNew job status (running)
contactsEnqueuedintegerNumber of contacts queued for processing
redisJobCancelledbooleanWhether Redis scheduled job was cancelled
startedAtstringStart time (ISO 8601, UTC)

​
Examples

​
Example 1: Start Scheduled Job Early

curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "message": "Cancelled scheduled job, starting immediately",
  "batchJobId": "batch_xyz789",
  "status": "running",
  "contactsEnqueued": 100,
  "redisJobCancelled": true,
  "startedAt": "2025-02-28T13:30:00Z"
}

​
Example 2: Start Pending Job

curl -X POST "https://api.talkifai.com/batch/jobs/batch_pending/start" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "success": true,
  "message": "Starting immediately",
  "batchJobId": "batch_pending",
  "status": "running",
  "contactsEnqueued": 50,
  "redisJobCancelled": false,
  "startedAt": "2025-02-28T13:30:00Z"
}

​
Example 3: Start Already Running Job (Error)

curl -X POST "https://api.talkifai.com/batch/jobs/batch_running/start" \
  -H "Authorization: Bearer YOUR_API_KEY"
Response: 
{
  "detail": "Cannot start job in 'running' status. Only 'scheduled' or 'pending' jobs can be started."
}

​
Behavior by Status

Job StatusStart Behavior
scheduledCancels Redis defer job + marks as running + enqueues all contacts
pendingMarks as running + enqueues all contacts
running❌ Error: Job already running
completed❌ Error: Cannot start completed job
failed❌ Error: Cannot start failed job
cancelled❌ Error: Cannot start cancelled job

​
How It Works

POST /batch/jobs/{id}/start
         │
         ▼
1. Check job status
         ├── Not scheduled/pending → 400 Error
         └── Scheduled/Pending → Continue
                   │
                   ▼
2. If scheduled: Cancel Redis defer job
         ├── Found → Cancel + clear scheduledJobId
         └── Not found → Proceed (already dequeued)
                   │
                   ▼
3. Update job status to 'running'
         │
         ▼
4. Fetch all pending contacts
         │
         ▼
5. Enqueue contacts to worker queue
         │
         ▼
6. Return success with count

​
Error Handling

​
404 Not Found

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

​
400 Bad Request

{
  "detail": "Cannot start job in 'running' status. Only 'scheduled' or 'pending' jobs can be started."
}
Error CodeCause
job_not_foundBatch job ID doesn’t exist
invalid_statusJob is not in scheduled or pending status
already_runningJob is already processing

​
500 Internal Server Error

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

​
Use Cases

​
Start Campaign Early

You scheduled a campaign for 9 AM but want to start at 8:30 AM: 
# Job scheduled for 9:00 AM
# At 8:30 AM, decide to start early
curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Manual Trigger After Creation

Create a job without scheduling, then start manually: 
# Create job without scheduledStartTime
curl -X POST "https://api.talkifai.com/batch/create" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@contacts.csv" \
  -F "fromPhoneNumberId=phone_abc123" \
  -F "name=Test Campaign"

# Job created with status 'pending'
# Start it when ready
curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \
  -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 started

​
success
boolean
Example:

true

​
message
string
Example:

"Cancelled scheduled job, starting immediately"

​
batchJobId
string
​
status
string
Example:

"running"

​
contactsEnqueued
integer
​
redisJobCancelled
boolean
​
startedAt
string<date-time>