Skip to main content
GET
/
batch
/
jobs
List Batch Jobs
curl --request GET \
  --url https://api.talkifai.dev/batch/jobs \
  --header 'Authorization: Bearer <token>'
{
  "batchJobs": [
    {
      "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,
      "scheduledStartTime": "2023-11-07T05:31:56Z",
      "actualStartTime": "2023-11-07T05:31:56Z",
      "completedAt": "2023-11-07T05:31:56Z",
      "createdAt": "2023-11-07T05:31:56Z",
      "concurrentCallLimit": 5,
      "retryPolicy": {
        "maxAttempts": 3,
        "retryableStatuses": [
          "no_answer",
          "busy",
          "timeout"
        ]
      }
    }
  ],
  "total": 47,
  "page": 1,
  "pageSize": 20
}

​
Overview

Retrieves all batch calling jobs for an organization with optional filtering by status. Supports pagination for large result sets.

​
Request

GET /batch/jobs?organizationId=org_abc123&status=running&page=1&pageSize=20

​
Query Parameters

ParameterTypeRequiredDefaultDescription
organizationIdstring✅—Organization ID to filter by
statusstring❌—Filter by job status
pageinteger❌1Page number (1-indexed)
pageSizeinteger❌20Items per page (1-100)

​
Status Filter Values

StatusDescription
pendingJob created, waiting to start
scheduledJob scheduled for future start
runningJob actively processing contacts
completedAll contacts processed successfully
failedJob failed due to errors
cancelledJob was cancelled manually

​
Response

{
  "batchJobs": [
    {
      "id": "batch_xyz789",
      "name": "January Renewal Campaign",
      "description": "Follow up on expiring subscriptions",
      "status": "running",
      "totalContacts": 100,
      "contactsProcessed": 42,
      "successfulCalls": 35,
      "failedCalls": 7,
      "scheduledStartTime": "2025-02-28T14:00:00Z",
      "actualStartTime": "2025-02-28T14:00:05Z",
      "completedAt": null,
      "createdAt": "2025-02-28T10:30:00Z"
    },
    {
      "id": "batch_abc123",
      "name": "Payment Reminders",
      "description": null,
      "status": "completed",
      "totalContacts": 50,
      "contactsProcessed": 50,
      "successfulCalls": 45,
      "failedCalls": 5,
      "scheduledStartTime": null,
      "actualStartTime": "2025-02-27T09:00:00Z",
      "completedAt": "2025-02-27T09:25:00Z",
      "createdAt": "2025-02-27T08:45:00Z"
    }
  ],
  "total": 47,
  "page": 1,
  "pageSize": 20
}

​
Response Fields

FieldTypeDescription
batchJobsarrayList of batch job objects
totalintegerTotal number of jobs matching filter
pageintegerCurrent page number
pageSizeintegerNumber of items per page

​
Batch Job Object

FieldTypeDescription
idstringUnique batch job identifier
namestringJob name
descriptionstringOptional description
statusstringCurrent job status
totalContactsintegerTotal contacts in job
contactsProcessedintegerNumber of contacts processed
successfulCallsintegerNumber of successful calls
failedCallsintegerNumber of failed calls
scheduledStartTimestringScheduled start time (ISO 8601, UTC)
actualStartTimestringActual start time (ISO 8601, UTC)
completedAtstringCompletion time (ISO 8601, UTC)
createdAtstringCreation time (ISO 8601, UTC)

​
Examples

​
Example 1: List All Jobs

curl -X GET "https://api.talkifai.com/batch/jobs?organizationId=org_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example 2: Filter by Running Status

curl -X GET "https://api.talkifai.com/batch/jobs?organizationId=org_abc123&status=running" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example 3: Paginated Results

curl -X GET "https://api.talkifai.com/batch/jobs?organizationId=org_abc123&page=2&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example 4: List Completed Jobs

curl -X GET "https://api.talkifai.com/batch/jobs?organizationId=org_abc123&status=completed" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Error Handling

​
400 Bad Request

{
  "detail": "Invalid page number: must be >= 1"
}
Error CodeCause
invalid_pagePage number less than 1
invalid_page_sizePage size outside 1-100 range
invalid_statusInvalid status filter value

​
500 Internal Server Error

{
  "detail": "Failed to list batch jobs"
}

​
Pagination

The API uses offset-based pagination: 
Page 1: Items 1-20
Page 2: Items 21-40
Page 3: Items 41-60
...
Calculate total pages: 
totalPages = ceil(total / pageSize)
Example:
  • Total: 47 jobs
  • Page size: 20
  • Total pages: 3

Authorizations

​
Authorization
string
header
required

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

Query Parameters

​
organizationId
string
required

Organization ID to filter by

​
status
enum<string>

Filter by job status

Available options:
pending,
scheduled,
running,
completed,
failed,
cancelled
​
page
integer
default:1

Page number

Required range: x >= 1
​
pageSize
integer
default:20

Items per page

Required range: 1 <= x <= 100

Response

List of batch jobs

​
batchJobs
object[]
​
total
integer
Example:

47

​
page
integer
Example:

1

​
pageSize
integer
Example:

20