List Call Batches

GET List all call batches

GET /api/v1/public/call-batches

Retrieve a paginated list of all call batches for your account. Filter by agent ID, status, or both.

Authorization

Authorization: Bearer sk_your_api_key

Query Parameters

Parameter	Type	Required	Description
agent_id	string	❌	Filter by agent ID (e.g., agt-57949b14)
status	string	❌	Filter by status: pending, active, completed, failed, cancelled
limit	integer	❌	Results per page. Default: 50, Max: 100
page	integer	❌	Page number (1-indexed). Default: 1

Code Examples

cURL

curl -X GET "https://api.staging.techladder.ai/api/v1/public/call-batches?agent_id=agt-57949b14&status=pending&limit=50&page=1" \
  -H "Authorization: Bearer sk_your_api_key" \
  -H "Accept: application/json"

Python

import requests

response = requests.get(
    "https://api.staging.techladder.ai/api/v1/public/call-batches",
    headers={"Authorization": "Bearer sk_your_api_key"},
    params={
        "agent_id": "agt-57949b14",
        "status": "pending",
        "limit": 50,
        "page": 1,
    },
)

print(response.json())

JavaScript

const params = new URLSearchParams({
  agent_id: "agt-57949b14",
  status: "pending",
  limit: "50",
  page: "1",
});

const response = await fetch(
  `https://api.staging.techladder.ai/api/v1/public/call-batches?${params}`,
  {
    headers: { Authorization: "Bearer sk_your_api_key" },
  }
);

const data = await response.json();
console.log(data);

Java

import java.net.URI;
import java.net.http.*;

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.staging.techladder.ai/api/v1/public/call-batches?agent_id=agt-57949b14&status=pending&limit=50&page=1"))
    .header("Authorization", "Bearer sk_your_api_key")
    .GET()
    .build();

HttpResponse<String> response = client.send(request,
    HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Responses

200 OK

A paginated list of call batches.

{
  "status_code": 200,
  "message": "Call batches fetched successfully",
  "error": null,
  "data": {
    "items": [
      {
        "schedule_id": "sched_7bac6f2a",
        "agent_id": "agt-57949b14",
        "agent_name": "Customer Outreach Agent",
        "version_id": "pmt-667ddf271b",
        "status": "pending",
        "start_mode": "scheduled",
        "total_contacts": 150,
        "completed_contacts": 0,
        "failed_contacts": 0,
        "scheduled_at": "2026-05-15T08:30:00Z",
        "created_at": "2026-05-14T10:00:00Z"
      }
    ],
    "total": 1,
    "page": 1,
    "limit": 50,
    "has_more": false
  }
}

401 Unauthorized

Returned when the API key is missing or invalid.

{
  "status_code": 401,
  "message": "Missing or invalid API key",
  "error": {
    "code": "UNAUTHORIZED",
    "details": ["Provide a valid Bearer token in the Authorization header"]
  },
  "data": null
}

422 Unprocessable Entity

Returned when query parameters fail validation (e.g. unknown status value).

{
  "status_code": 422,
  "message": "Invalid query parameters",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": ["status: Must be one of pending, active, completed, failed, cancelled"]
  },
  "data": null
}

Batch Status Values

Status	Description
pending	Batch created but not yet started
active	Batch is currently running calls
completed	All calls in the batch have finished
failed	Batch encountered an error
cancelled	Batch was manually cancelled