Get Batch Job Detail

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.talkifai.dev/batch/jobs/{batch_job_id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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}"

	req, _ := http.NewRequest("GET", 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.get("https://api.talkifai.dev/batch/jobs/{batch_job_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "status": "<string>",
  "organizationId": "<string>",
  "agentId": "<string>",
  "fromPhoneNumberId": "<string>",
  "totalContacts": 123,
  "contactsProcessed": 123,
  "successfulCalls": 123,
  "failedCalls": 123,
  "statusBreakdown": {},
  "scheduledStartTime": "2023-11-07T05:31:56Z",
  "actualStartTime": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "estimatedCompletionTime": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "concurrentCallLimit": 123,
  "retryPolicy": {},
  "contacts": [
    {
      "id": "contact_001",
      "phoneNumber": "+12025550101",
      "contactData": {
        "phone": "+12025550101",
        "name": "John Smith",
        "customerName": "John Smith"
      },
      "status": "completed",
      "errorCode": "480",
      "attemptCount": 1,
      "maxAttempts": 3,
      "lastAttemptAt": "2023-11-07T05:31:56Z",
      "nextRetryAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "roomName": "<string>",
      "failureReason": "<string>",
      "callDuration": 123
    }
  ],
  "contactsTotal": 123,
  "contactsPage": 123,
  "contactsPageSize": 123,
  "contactsHasMore": true
}

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

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

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

GET

batch

jobs

{batch_job_id}

Get Batch Job Detail

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

import requests

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

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

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

print(response.text)

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

fetch('https://api.talkifai.dev/batch/jobs/{batch_job_id}', 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}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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}"

	req, _ := http.NewRequest("GET", 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.get("https://api.talkifai.dev/batch/jobs/{batch_job_id}")
  .header("Authorization", "Bearer <token>")
  .asString();

require 'uri'
require 'net/http'

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

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

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

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

{
  "id": "<string>",
  "name": "<string>",
  "description": "<string>",
  "status": "<string>",
  "organizationId": "<string>",
  "agentId": "<string>",
  "fromPhoneNumberId": "<string>",
  "totalContacts": 123,
  "contactsProcessed": 123,
  "successfulCalls": 123,
  "failedCalls": 123,
  "statusBreakdown": {},
  "scheduledStartTime": "2023-11-07T05:31:56Z",
  "actualStartTime": "2023-11-07T05:31:56Z",
  "completedAt": "2023-11-07T05:31:56Z",
  "estimatedCompletionTime": "2023-11-07T05:31:56Z",
  "createdAt": "2023-11-07T05:31:56Z",
  "concurrentCallLimit": 123,
  "retryPolicy": {},
  "contacts": [
    {
      "id": "contact_001",
      "phoneNumber": "+12025550101",
      "contactData": {
        "phone": "+12025550101",
        "name": "John Smith",
        "customerName": "John Smith"
      },
      "status": "completed",
      "errorCode": "480",
      "attemptCount": 1,
      "maxAttempts": 3,
      "lastAttemptAt": "2023-11-07T05:31:56Z",
      "nextRetryAt": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "roomName": "<string>",
      "failureReason": "<string>",
      "callDuration": 123
    }
  ],
  "contactsTotal": 123,
  "contactsPage": 123,
  "contactsPageSize": 123,
  "contactsHasMore": true
}

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

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

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

Overview

Retrieves comprehensive information about a specific batch job including:

Job configuration and status
Progress statistics
Status breakdown (count by status)
Timing information (scheduled, started, completed, estimated)
Paginated list of contacts with optional status filtering

Request

GET /batch/jobs/{batch_job_id}?contactStatus=completed&contactsPage=1&contactsPageSize=50

Path Parameters

Parameter	Type	Required	Description
`batch_job_id`	string	✅	Unique batch job identifier

Query Parameters

Parameter	Type	Required	Default	Description
`contactStatus`	string	❌	—	Filter contacts by status
`contactsPage`	integer	❌	`1`	Contacts page number (1-indexed)
`contactsPageSize`	integer	❌	`50`	Contacts per page (1-500)

Contact Status Filter Values

Status	Description
`pending`	Contact waiting to be called
`queued`	Contact queued for retry
`dialing`	Call currently in progress
`completed`	Call completed successfully
`no_answer`	Call not answered
`busy`	Line was busy
`timeout`	Call timed out
`blocked`	Call blocked by carrier
`invalid_number`	Phone number invalid
`carrier_error`	Carrier/network error
`failed`	Call failed (other reason)
`cancelled`	Contact cancelled

Response

{
  "id": "batch_xyz789",
  "name": "January Renewal Campaign",
  "description": "Follow up on expiring subscriptions",
  "status": "running",
  "organizationId": "org_abc123",
  "agentId": "agent_def456",
  "fromPhoneNumberId": "phone_ghi789",
  "totalContacts": 100,
  "contactsProcessed": 42,
  "successfulCalls": 35,
  "failedCalls": 7,
  "statusBreakdown": {
    "pending": 55,
    "dialing": 3,
    "completed": 35,
    "failed": 5,
    "no_answer": 2
  },
  "scheduledStartTime": "2025-02-28T14:00:00Z",
  "actualStartTime": "2025-02-28T14:00:05Z",
  "completedAt": null,
  "estimatedCompletionTime": "2025-02-28T14:25:00Z",
  "createdAt": "2025-02-28T10:30:00Z",
  "concurrentCallLimit": 5,
  "retryPolicy": {
    "maxAttempts": 3,
    "retryableStatuses": ["no_answer", "busy", "timeout"]
  },
  "contacts": [
    {
      "id": "contact_001",
      "phoneNumber": "+12025550101",
      "contactData": {
        "phone": "+12025550101",
        "name": "John Smith",
        "customerName": "John Smith",
        "renewalDate": "Feb 1"
      },
      "status": "completed",
      "errorCode": null,
      "attemptCount": 1,
      "maxAttempts": 3,
      "lastAttemptAt": "2025-02-28T14:05:00Z",
      "nextRetryAt": null,
      "completedAt": "2025-02-28T14:05:30Z",
      "roomName": "outbound_agent_def456_12025550101_1709128800",
      "failureReason": null,
      "callDuration": 120
    },
    {
      "id": "contact_002",
      "phoneNumber": "+12025550102",
      "contactData": {
        "phone": "+12025550102",
        "name": "Jane Doe",
        "customerName": "Jane Doe",
        "renewalDate": "Feb 5"
      },
      "status": "no_answer",
      "errorCode": "480",
      "attemptCount": 2,
      "maxAttempts": 3,
      "lastAttemptAt": "2025-02-28T14:06:00Z",
      "nextRetryAt": "2025-02-28T14:11:00Z",
      "completedAt": null,
      "roomName": null,
      "failureReason": "SIP status: 480 Temporarily Unavailable",
      "callDuration": null
    }
  ],
  "contactsTotal": 100,
  "contactsPage": 1,
  "contactsPageSize": 50,
  "contactsHasMore": true
}

Response Fields

Job Info

Field	Type	Description
`id`	string	Unique batch job identifier
`name`	string	Job name
`description`	string	Optional description
`status`	string	Current job status
`organizationId`	string	Organization ID
`agentId`	string	Agent ID used for calls
`fromPhoneNumberId`	string	Phone number ID used for calls

Progress Stats

Field	Type	Description
`totalContacts`	integer	Total contacts in job
`contactsProcessed`	integer	Number of contacts processed
`successfulCalls`	integer	Number of successful calls
`failedCalls`	integer	Number of failed calls
`statusBreakdown`	object	Count per status

Timing Info

Field	Type	Description
`scheduledStartTime`	string	Scheduled start time (ISO 8601, UTC)
`actualStartTime`	string	Actual start time (ISO 8601, UTC)
`completedAt`	string	Completion time (ISO 8601, UTC)
`estimatedCompletionTime`	string	Estimated completion (ISO 8601, UTC)
`createdAt`	string	Creation time (ISO 8601, UTC)

Settings

Field	Type	Description
`concurrentCallLimit`	integer	Max concurrent calls
`retryPolicy`	object	Retry configuration

Contacts List

Field	Type	Description
`contacts`	array	List of contact objects
`contactsTotal`	integer	Total contacts (with filter)
`contactsPage`	integer	Current contacts page
`contactsPageSize`	integer	Contacts per page
`contactsHasMore`	boolean	Whether more pages exist

Contact Object

Field	Type	Description
`id`	string	Contact identifier
`phoneNumber`	string	Phone number (E.164 format)
`contactData`	object	Original contact data + custom fields
`status`	string	Current contact status
`errorCode`	string	SIP error code (if failed)
`attemptCount`	integer	Number of attempts made
`maxAttempts`	integer	Maximum allowed attempts
`lastAttemptAt`	string	Last attempt time (ISO 8601, UTC)
`nextRetryAt`	string	Next retry time (ISO 8601, UTC)
`completedAt`	string	Completion time (ISO 8601, UTC)
`roomName`	string	LiveKit room name (if connected)
`failureReason`	string	Error message (if failed)
`callDuration`	integer	Call duration in seconds (if completed)

Examples

Example 1: Get Full Job Detail

curl -X GET "https://api.talkifai.com/batch/jobs/batch_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example 2: Get Only Completed Contacts

curl -X GET "https://api.talkifai.com/batch/jobs/batch_xyz789?contactStatus=completed&contactsPage=1&contactsPageSize=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example 3: Get Failed Contacts for Analysis

curl -X GET "https://api.talkifai.com/batch/jobs/batch_xyz789?contactStatus=no_answer&contactsPage=1&contactsPageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example 4: Get Pending Contacts

curl -X GET "https://api.talkifai.com/batch/jobs/batch_xyz789?contactStatus=pending&contactsPage=1&contactsPageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Error Handling

404 Not Found

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

400 Bad Request

{
  "detail": "Invalid contact status filter value"
}

Error Code	Cause
`invalid_contact_status`	Invalid contact status filter
`invalid_page`	Page number less than 1
`invalid_page_size`	Page size outside 1-500 range

500 Internal Server Error

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

Status Breakdown Interpretation

The statusBreakdown object shows count of contacts in each status:

{
  "statusBreakdown": {
    "pending": 55,      // Waiting to be called
    "dialing": 3,       // Currently being called
    "completed": 35,    // Successfully completed
    "failed": 5,        // Failed (non-retryable)
    "no_answer": 2      // No answer (will retry)
  }
}

Calculate remaining contacts:

remaining = statusBreakdown.pending + statusBreakdown.queued + statusBreakdown.dialing

Calculate success rate:

successRate = successfulCalls / contactsProcessed * 100

Estimated Completion Time

For running jobs, the API calculates estimated completion based on:

Elapsed time since start
Number of contacts processed
Remaining contacts

Formula:

avgTimePerContact = elapsedSeconds / contactsProcessed
remainingSeconds = (totalContacts - contactsProcessed) * avgTimePerContact
estimatedCompletion = actualStartTime + remainingSeconds

Estimated completion is approximate and may vary based on retry attempts, concurrency, and call duration.

Create Batch Job — Create a new batch job
List Batch Jobs — List all batch jobs
Cancel Batch Job — Cancel a running job
Start Batch Job — Start a scheduled job immediately
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

Query Parameters

contactStatus

enum<string>

Filter contacts by status

Available options:

pending,

queued,

dialing,

completed,

no_answer,

busy,

timeout,

blocked,

invalid_number,

carrier_error,

failed,

cancelled

contactsPage

integer

default:1

Required range: x >= 1

contactsPageSize

integer

default:50

Required range: 1 <= x <= 500

Response

Batch job details

string

name

string

description

string | null

status

string

organizationId

string

agentId

string

fromPhoneNumberId

string

totalContacts

integer

contactsProcessed

integer

successfulCalls

integer

failedCalls

integer

statusBreakdown

object

Show child attributes

scheduledStartTime

string<date-time> | null

actualStartTime

string<date-time> | null

completedAt

string<date-time> | null

estimatedCompletionTime

string<date-time> | null

createdAt

string<date-time>

concurrentCallLimit

integer

retryPolicy

object

contacts

object[]

Show child attributes

contactsTotal

integer

contactsPage

integer

contactsPageSize

integer

contactsHasMore

boolean

List Batch Jobs Start Batch Job Immediately

Overview

Agents

Voice Calls

Export

Text Chat

Batch Calling

Custom Functions

Webhooks

Get Batch Job Detail

Overview

Request

Path Parameters

Query Parameters

Contact Status Filter Values

Response

Response Fields

Job Info

Progress Stats

Timing Info

Settings

Contacts List

Contact Object

Examples

Example 1: Get Full Job Detail

Example 2: Get Only Completed Contacts

Example 3: Get Failed Contacts for Analysis

Example 4: Get Pending Contacts

Error Handling

404 Not Found

400 Bad Request

500 Internal Server Error

Status Breakdown Interpretation

Estimated Completion Time

Authorizations

Path Parameters

Query Parameters

Response

​Overview

​Request

​Path Parameters

​Query Parameters

​Contact Status Filter Values

​Response

​Response Fields

​Job Info

​Progress Stats

​Timing Info

​Settings

​Contacts List

​Contact Object

​Examples

​Example 1: Get Full Job Detail

​Example 2: Get Only Completed Contacts

​Example 3: Get Failed Contacts for Analysis

​Example 4: Get Pending Contacts

​Error Handling

​404 Not Found

​400 Bad Request

​500 Internal Server Error

​Status Breakdown Interpretation

​Estimated Completion Time

​Related

Authorizations

Path Parameters

Query Parameters

Response

Overview

Request

Path Parameters

Query Parameters

Contact Status Filter Values

Response

Response Fields

Job Info

Progress Stats

Timing Info

Settings

Contacts List

Contact Object

Examples

Example 1: Get Full Job Detail

Example 2: Get Only Completed Contacts

Example 3: Get Failed Contacts for Analysis

Example 4: Get Pending Contacts

Error Handling

404 Not Found

400 Bad Request

500 Internal Server Error

Status Breakdown Interpretation

Estimated Completion Time

Related