Skip to main content
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>'
{
  "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
}

​
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

ParameterTypeRequiredDescription
batch_job_idstring✅Unique batch job identifier

​
Query Parameters

ParameterTypeRequiredDefaultDescription
contactStatusstring❌—Filter contacts by status
contactsPageinteger❌1Contacts page number (1-indexed)
contactsPageSizeinteger❌50Contacts per page (1-500)

​
Contact Status Filter Values

StatusDescription
pendingContact waiting to be called
queuedContact queued for retry
dialingCall currently in progress
completedCall completed successfully
no_answerCall not answered
busyLine was busy
timeoutCall timed out
blockedCall blocked by carrier
invalid_numberPhone number invalid
carrier_errorCarrier/network error
failedCall failed (other reason)
cancelledContact 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

FieldTypeDescription
idstringUnique batch job identifier
namestringJob name
descriptionstringOptional description
statusstringCurrent job status
organizationIdstringOrganization ID
agentIdstringAgent ID used for calls
fromPhoneNumberIdstringPhone number ID used for calls

​
Progress Stats

FieldTypeDescription
totalContactsintegerTotal contacts in job
contactsProcessedintegerNumber of contacts processed
successfulCallsintegerNumber of successful calls
failedCallsintegerNumber of failed calls
statusBreakdownobjectCount per status

​
Timing Info

FieldTypeDescription
scheduledStartTimestringScheduled start time (ISO 8601, UTC)
actualStartTimestringActual start time (ISO 8601, UTC)
completedAtstringCompletion time (ISO 8601, UTC)
estimatedCompletionTimestringEstimated completion (ISO 8601, UTC)
createdAtstringCreation time (ISO 8601, UTC)

​
Settings

FieldTypeDescription
concurrentCallLimitintegerMax concurrent calls
retryPolicyobjectRetry configuration

​
Contacts List

FieldTypeDescription
contactsarrayList of contact objects
contactsTotalintegerTotal contacts (with filter)
contactsPageintegerCurrent contacts page
contactsPageSizeintegerContacts per page
contactsHasMorebooleanWhether more pages exist

​
Contact Object

FieldTypeDescription
idstringContact identifier
phoneNumberstringPhone number (E.164 format)
contactDataobjectOriginal contact data + custom fields
statusstringCurrent contact status
errorCodestringSIP error code (if failed)
attemptCountintegerNumber of attempts made
maxAttemptsintegerMaximum allowed attempts
lastAttemptAtstringLast attempt time (ISO 8601, UTC)
nextRetryAtstringNext retry time (ISO 8601, UTC)
completedAtstringCompletion time (ISO 8601, UTC)
roomNamestringLiveKit room name (if connected)
failureReasonstringError message (if failed)
callDurationintegerCall 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 CodeCause
invalid_contact_statusInvalid contact status filter
invalid_pagePage number less than 1
invalid_page_sizePage 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.

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

​
id
string
​
name
string
​
description
string | null
​
status
string
​
organizationId
string
​
agentId
string
​
fromPhoneNumberId
string
​
totalContacts
integer
​
contactsProcessed
integer
​
successfulCalls
integer
​
failedCalls
integer
​
statusBreakdown
object
​
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[]
​
contactsTotal
integer
​
contactsPage
integer
​
contactsPageSize
integer
​
contactsHasMore
boolean