Trillet AI logo

Get Batch Status

Get status and counters for a batch call operation

GEThttps://api.trillet.ai/v1/api/batch-calls/{batchId}

Headers

x-workspace-idstringrequired

Workspace identifier for the API.

Path Parameters

batchIdstringrequired

The 10-character batch ID returned by Start Batch Calls.

Live tracking for a batch is kept for 7 days. After that, a batch that already ran returns 404 Batch not found. Use Call History filtered by batchId, or GET /v1/api/batch-history/batch/{batchId}, for older batches. A scheduled batch that hasn't started yet is always found.

Response

existsboolean

Always true on a 200 response.

batchIdstring

The batch ID.

statusstring

Status worked out from the counters:

  • scheduled - The batch has a future start time and no calls have been queued yet
  • queued - Calls are waiting and none has completed yet
  • processing - Calls are being placed
  • completed - Nothing is waiting or active, and every job completed, failed or was cancelled one at a time
  • failed - Nothing is waiting or active, and every job failed
  • cancelled - The batch was stopped with Cancel Batch Operation. This status is final: a stopped batch never reads completed. Calls already in progress when it was stopped still finish, and their outcomes still count in completed or failed
countersobject

Job counters for the batch.

timestampnumber

Time this status was read, in Unix milliseconds.

progressobject

The same object Get Batch Progress returns: batchId, total, completed, failed, cancelled, waiting, active, progress (percent completed, 0-100) and lastUpdated (Unix milliseconds).

scheduledAtstring

Scheduled batches only. Start time as an ISO 8601 string.

scheduledTimezonestring | null

Scheduled batches only. The scheduledTimezone sent when the batch was created, or null.

timezonestring | null

Scheduled batches only. The call flow's office-hours timezone.

Example Usage

curl -X GET "https://api.trillet.ai/v1/api/batch-calls/k3j9x0a1bq" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-workspace-id: YOUR_WORKSPACE_ID"

Example Response

{
  "exists": true,
  "batchId": "k3j9x0a1bq",
  "status": "processing",
  "counters": {
    "waiting": 45,
    "active": 5,
    "completed": 95,
    "failed": 5,
    "cancelled": 0,
    "total": 150
  },
  "timestamp": 1793284800000,
  "progress": {
    "batchId": "k3j9x0a1bq",
    "total": 150,
    "completed": 95,
    "failed": 5,
    "cancelled": 0,
    "waiting": 45,
    "active": 5,
    "progress": 63,
    "lastUpdated": 1793284800000
  }
}

Example Response (scheduled)

{
  "exists": true,
  "batchId": "p8d2m4t7zs",
  "status": "scheduled",
  "scheduledAt": "2026-11-15T14:30:00.000Z",
  "scheduledTimezone": "America/New_York",
  "timezone": "America/New_York",
  "counters": { "waiting": 0, "active": 0, "completed": 0, "failed": 0, "cancelled": 0, "total": 150 },
  "timestamp": 1793284800000,
  "progress": {
    "batchId": "p8d2m4t7zs",
    "total": 0,
    "completed": 0,
    "failed": 0,
    "cancelled": 0,
    "waiting": 0,
    "active": 0,
    "progress": 0,
    "lastUpdated": 1793284800000
  }
}

Error Responses

errorstring

Error message describing what went wrong

messagestring

Additional context about the error

idstring

The batch ID that was not found (on some 404 responses)

Common Error Codes:

  • 404 - Batch not found: the batch doesn't exist, belongs to another workspace, or its 7-day tracking window has passed
  • 500 - Server error retrieving batch information

Status Monitoring

Poll this endpoint to follow a running batch. For per-call outcomes, transcripts and analysis, use Call History filtered by batchId.

Last updated on