> ## Documentation Index
> Fetch the complete documentation index at: https://docs.talkifai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# List Batch Jobs

> Returns a paginated list of batch calling jobs for your organization.

## Overview

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

## Request

```bash theme={null}
GET /batch/jobs?organizationId=org_abc123&status=running&page=1&pageSize=20
```

## Query Parameters

| Parameter        | Type    | Required | Default | Description                  |
| ---------------- | ------- | -------- | ------- | ---------------------------- |
| `organizationId` | string  | ✅        | —       | Organization ID to filter by |
| `status`         | string  | ❌        | —       | Filter by job status         |
| `page`           | integer | ❌        | `1`     | Page number (1-indexed)      |
| `pageSize`       | integer | ❌        | `20`    | Items per page (1-100)       |

### Status Filter Values

| Status      | Description                         |
| ----------- | ----------------------------------- |
| `pending`   | Job created, waiting to start       |
| `scheduled` | Job scheduled for future start      |
| `running`   | Job actively processing contacts    |
| `completed` | All contacts processed successfully |
| `failed`    | Job failed due to errors            |
| `cancelled` | Job was cancelled manually          |

## Response

```json theme={null}
{
  "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

| Field       | Type    | Description                          |
| ----------- | ------- | ------------------------------------ |
| `batchJobs` | array   | List of batch job objects            |
| `total`     | integer | Total number of jobs matching filter |
| `page`      | integer | Current page number                  |
| `pageSize`  | integer | Number of items per page             |

### Batch Job Object

| Field                | Type    | Description                          |
| -------------------- | ------- | ------------------------------------ |
| `id`                 | string  | Unique batch job identifier          |
| `name`               | string  | Job name                             |
| `description`        | string  | Optional description                 |
| `status`             | string  | Current job status                   |
| `totalContacts`      | integer | Total contacts in job                |
| `contactsProcessed`  | integer | Number of contacts processed         |
| `successfulCalls`    | integer | Number of successful calls           |
| `failedCalls`        | integer | Number of failed calls               |
| `scheduledStartTime` | string  | Scheduled start time (ISO 8601, UTC) |
| `actualStartTime`    | string  | Actual start time (ISO 8601, UTC)    |
| `completedAt`        | string  | Completion time (ISO 8601, UTC)      |
| `createdAt`          | string  | Creation time (ISO 8601, UTC)        |

## Examples

### Example 1: List All Jobs

```bash theme={null}
curl -X GET "https://api.talkifai.com/batch/jobs?organizationId=org_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Example 2: Filter by Running Status

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

### Example 3: Paginated Results

```bash theme={null}
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

```bash theme={null}
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

```json theme={null}
{
  "detail": "Invalid page number: must be >= 1"
}
```

| Error Code          | Cause                         |
| ------------------- | ----------------------------- |
| `invalid_page`      | Page number less than 1       |
| `invalid_page_size` | Page size outside 1-100 range |
| `invalid_status`    | Invalid status filter value   |

### 500 Internal Server Error

```json theme={null}
{
  "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

## Related

* [Create Batch Job](/api-reference/endpoint/create-batch-job) — Create a new batch job
* [Get Batch Job Detail](/api-reference/endpoint/get-batch-job) — Get detailed job info
* [Cancel Batch Job](/api-reference/endpoint/cancel-batch-job) — Cancel a running job
* [Batch Calling Guide](/platform/batch-calling) — Complete guide to batch campaigns


## OpenAPI

````yaml GET /batch/jobs
openapi: 3.1.0
info:
  title: TalkifAI API
  version: 1.0.0
  description: Build and manage AI voice and chat agents programmatically.
servers:
  - url: https://api.talkifai.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Agents
    description: Create and manage voice and chat agents
  - name: Voice Calls
    description: Initiate outbound calls and retrieve call data
  - name: Text Chat
    description: Text chat sessions via REST + SSE
  - name: Batch Calling
    description: Run large-scale outbound call campaigns
paths:
  /batch/jobs:
    get:
      tags:
        - Batch Calling
      summary: List Batch Jobs
      description: Returns a paginated list of batch calling jobs for an organization.
      operationId: listBatchJobs
      parameters:
        - name: organizationId
          in: query
          required: true
          schema:
            type: string
          description: Organization ID to filter by
        - name: status
          in: query
          required: false
          schema:
            type: string
            enum:
              - pending
              - scheduled
              - running
              - completed
              - failed
              - cancelled
          description: Filter by job status
        - name: page
          in: query
          schema:
            type: integer
            default: 1
            minimum: 1
          description: Page number
        - name: pageSize
          in: query
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Items per page
      responses:
        '200':
          description: List of batch jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchJobListResponse'
        '400':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  schemas:
    BatchJobListResponse:
      type: object
      properties:
        batchJobs:
          type: array
          items:
            $ref: '#/components/schemas/BatchJob'
        total:
          type: integer
          example: 47
        page:
          type: integer
          example: 1
        pageSize:
          type: integer
          example: 20
    Error:
      type: object
      properties:
        success:
          type: boolean
          example: false
        error:
          type: string
          example: Error message
        code:
          type: string
          example: ERROR_CODE
    BatchJob:
      type: object
      properties:
        id:
          type: string
          example: batch_xyz789
        name:
          type: string
          example: January Renewal Campaign
        description:
          type: string
          nullable: true
          example: Follow up on expiring subscriptions
        status:
          type: string
          enum:
            - pending
            - scheduled
            - running
            - completed
            - failed
            - cancelled
          example: running
        organizationId:
          type: string
          example: org_abc123
        agentId:
          type: string
          example: agent_def456
        fromPhoneNumberId:
          type: string
          example: phone_ghi789
        totalContacts:
          type: integer
          example: 100
        contactsProcessed:
          type: integer
          example: 42
        successfulCalls:
          type: integer
          example: 35
        failedCalls:
          type: integer
          example: 7
        scheduledStartTime:
          type: string
          format: date-time
          nullable: true
        actualStartTime:
          type: string
          format: date-time
          nullable: true
        completedAt:
          type: string
          format: date-time
          nullable: true
        createdAt:
          type: string
          format: date-time
        concurrentCallLimit:
          type: integer
          example: 5
        retryPolicy:
          type: object
          properties:
            maxAttempts:
              type: integer
              example: 3
            retryableStatuses:
              type: array
              items:
                type: string
              example:
                - no_answer
                - busy
                - timeout
  responses:
    Unauthorized:
      description: Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            success: false
            error: Invalid API key
            code: invalid_api_key
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: tk_live_...
      description: Your TalkifAI API key. Get it from Studio → Settings → API Keys.

````