Start Batch Job Immediately

curl --request POST \
  --url https://api.talkifai.dev/batch/jobs/{batch_job_id}/start \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.talkifai.dev/batch/jobs/{batch_job_id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.talkifai.dev/batch/jobs/{batch_job_id}/start")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.talkifai.dev/batch/jobs/{batch_job_id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Cancelled scheduled job, starting immediately",
  "batchJobId": "<string>",
  "status": "running",
  "contactsEnqueued": 123,
  "redisJobCancelled": true,
  "startedAt": "2023-11-07T05:31:56Z"
}

{
  "detail": "Cannot start job in 'running' status"
}

{
  "success": false,
  "error": "Invalid API key",
  "code": "invalid_api_key"
}

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

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>'

import requests

url = "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start"

headers = {"Authorization": "Bearer <token>"}

response = requests.post(url, headers=headers)

print(response.text)

const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.talkifai.dev/batch/jobs/{batch_job_id}/start', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.talkifai.dev/batch/jobs/{batch_job_id}/start"

	req, _ := http.NewRequest("POST", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.talkifai.dev/batch/jobs/{batch_job_id}/start")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.talkifai.dev/batch/jobs/{batch_job_id}/start")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "success": true,
  "message": "Cancelled scheduled job, starting immediately",
  "batchJobId": "<string>",
  "status": "running",
  "contactsEnqueued": 123,
  "redisJobCancelled": true,
  "startedAt": "2023-11-07T05:31:56Z"
}

{
  "detail": "Cannot start job in 'running' status"
}

{
  "success": false,
  "error": "Invalid API key",
  "code": "invalid_api_key"
}

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

{
  "success": false,
  "error": "Error message",
  "code": "ERROR_CODE"
}

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

Parameter	Type	Required	Description
`batch_job_id`	string	✅	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

Field	Type	Description
`success`	boolean	Whether start succeeded
`message`	string	Start result description
`batchJobId`	string	Started batch job ID
`status`	string	New job status (`running`)
`contactsEnqueued`	integer	Number of contacts queued for processing
`redisJobCancelled`	boolean	Whether Redis scheduled job was cancelled
`startedAt`	string	Start 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 Status	Start Behavior
`scheduled`	Cancels Redis defer job + marks as `running` + enqueues all contacts
`pending`	Marks 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 Code	Cause
`job_not_found`	Batch job ID doesn’t exist
`invalid_status`	Job is not in `scheduled` or `pending` status
`already_running`	Job 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"

Create Batch Job — Create a new batch job
Cancel Batch Job — Cancel a job
Reschedule Batch Job — Change scheduled time
Get Batch Job Detail — Get job status
Batch Calling Guide — Complete guide to batch campaigns

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>

Get Batch Job Detail Cancel Batch Job

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

Start Batch Job Immediately

Overview

Request

Path Parameters

Response

Response Fields

Examples

Example 1: Start Scheduled Job Early

Example 2: Start Pending Job

Example 3: Start Already Running Job (Error)

Behavior by Status

How It Works

Error Handling

404 Not Found

400 Bad Request

500 Internal Server Error

Use Cases

Start Campaign Early

Manual Trigger After Creation

Authorizations

Path Parameters

Response

​Overview

​Request

​Path Parameters

​Response

​Response Fields

​Examples

​Example 1: Start Scheduled Job Early

​Example 2: Start Pending Job

​Example 3: Start Already Running Job (Error)

​Behavior by Status

​How It Works

​Error Handling

​404 Not Found

​400 Bad Request

​500 Internal Server Error

​Use Cases

​Start Campaign Early

​Manual Trigger After Creation

​Related

Authorizations

Path Parameters

Response

Overview

Request

Path Parameters

Response

Response Fields

Examples

Example 1: Start Scheduled Job Early

Example 2: Start Pending Job

Example 3: Start Already Running Job (Error)

Behavior by Status

How It Works

Error Handling

404 Not Found

400 Bad Request

500 Internal Server Error

Use Cases

Start Campaign Early

Manual Trigger After Creation

Related