> ## 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. # Start Batch Job Immediately > Manually start a scheduled or pending batch job immediately, bypassing the scheduled start time. ## Overview Starts a scheduled or pending batch job immediately, without waiting for the scheduled start time. **Use cases:** * Start a scheduled job ahead of time * Manually trigger a job that was created but not started * Override scheduling and begin processing now Only works for jobs in `scheduled` or `pending` status. Running jobs cannot be started again. ## Request ```bash theme={null} POST /batch/jobs/{batch_job_id}/start ``` ## Path Parameters | Parameter | Type | Required | Description | | -------------- | ------ | -------- | --------------------------- | | `batch_job_id` | string | ✅ | Unique batch job identifier | ## Response ```json theme={null} { "success": true, "message": "Cancelled scheduled job, starting immediately", "batchJobId": "batch_xyz789", "status": "running", "contactsEnqueued": 100, "redisJobCancelled": true, "startedAt": "2025-02-28T13:30:00Z" } ``` ### Response Fields | Field | Type | Description | | ------------------- | ------- | ----------------------------------------- | | `success` | boolean | Whether start succeeded | | `message` | string | Start result description | | `batchJobId` | string | Started batch job ID | | `status` | string | New job status (`running`) | | `contactsEnqueued` | integer | Number of contacts queued for processing | | `redisJobCancelled` | boolean | Whether Redis scheduled job was cancelled | | `startedAt` | string | Start time (ISO 8601, UTC) | ## Examples ### Example 1: Start Scheduled Job Early ```bash theme={null} curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response:** ```json theme={null} { "success": true, "message": "Cancelled scheduled job, starting immediately", "batchJobId": "batch_xyz789", "status": "running", "contactsEnqueued": 100, "redisJobCancelled": true, "startedAt": "2025-02-28T13:30:00Z" } ``` ### Example 2: Start Pending Job ```bash theme={null} curl -X POST "https://api.talkifai.com/batch/jobs/batch_pending/start" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response:** ```json theme={null} { "success": true, "message": "Starting immediately", "batchJobId": "batch_pending", "status": "running", "contactsEnqueued": 50, "redisJobCancelled": false, "startedAt": "2025-02-28T13:30:00Z" } ``` ### Example 3: Start Already Running Job (Error) ```bash theme={null} curl -X POST "https://api.talkifai.com/batch/jobs/batch_running/start" \ -H "Authorization: Bearer YOUR_API_KEY" ``` **Response:** ```json theme={null} { "detail": "Cannot start job in 'running' status. Only 'scheduled' or 'pending' jobs can be started." } ``` ## Behavior by Status | Job Status | Start Behavior | | ----------- | -------------------------------------------------------------------- | | `scheduled` | Cancels Redis defer job + marks as `running` + enqueues all contacts | | `pending` | Marks as `running` + enqueues all contacts | | `running` | ❌ Error: Job already running | | `completed` | ❌ Error: Cannot start completed job | | `failed` | ❌ Error: Cannot start failed job | | `cancelled` | ❌ Error: Cannot start cancelled job | ## How It Works ``` POST /batch/jobs/{id}/start │ ▼ 1. Check job status ├── Not scheduled/pending → 400 Error └── Scheduled/Pending → Continue │ ▼ 2. If scheduled: Cancel Redis defer job ├── Found → Cancel + clear scheduledJobId └── Not found → Proceed (already dequeued) │ ▼ 3. Update job status to 'running' │ ▼ 4. Fetch all pending contacts │ ▼ 5. Enqueue contacts to worker queue │ ▼ 6. Return success with count ``` ## Error Handling ### 404 Not Found ```json theme={null} { "detail": "Batch job not found" } ``` ### 400 Bad Request ```json theme={null} { "detail": "Cannot start job in 'running' status. Only 'scheduled' or 'pending' jobs can be started." } ``` | Error Code | Cause | | ----------------- | --------------------------------------------- | | `job_not_found` | Batch job ID doesn't exist | | `invalid_status` | Job is not in `scheduled` or `pending` status | | `already_running` | Job is already processing | ### 500 Internal Server Error ```json theme={null} { "detail": "Failed to start batch job" } ``` ## Use Cases ### Start Campaign Early You scheduled a campaign for 9 AM but want to start at 8:30 AM: ```bash theme={null} # Job scheduled for 9:00 AM # At 8:30 AM, decide to start early curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ### Manual Trigger After Creation Create a job without scheduling, then start manually: ```bash theme={null} # Create job without scheduledStartTime curl -X POST "https://api.talkifai.com/batch/create" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "file=@contacts.csv" \ -F "fromPhoneNumberId=phone_abc123" \ -F "name=Test Campaign" # Job created with status 'pending' # Start it when ready curl -X POST "https://api.talkifai.com/batch/jobs/batch_xyz789/start" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ## Related * [Create Batch Job](/api-reference/endpoint/create-batch-job) — Create a new batch job * [Cancel Batch Job](/api-reference/endpoint/cancel-batch-job) — Cancel a job * [Reschedule Batch Job](/api-reference/endpoint/reschedule-batch-job) — Change scheduled time * [Get Batch Job Detail](/api-reference/endpoint/get-batch-job) — Get job status * [Batch Calling Guide](/platform/batch-calling) — Complete guide to batch campaigns ## OpenAPI ````yaml POST /batch/jobs/{batch_job_id}/start 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/{batch_job_id}/start: post: tags: - Batch Calling summary: Start Batch Job Immediately description: >- Manually start a scheduled or pending batch job immediately, bypassing the scheduled start time. operationId: startBatchJob parameters: - name: batch_job_id in: path required: true schema: type: string responses: '200': description: Batch job started content: application/json: schema: type: object properties: success: type: boolean example: true message: type: string example: Cancelled scheduled job, starting immediately batchJobId: type: string status: type: string example: running contactsEnqueued: type: integer redisJobCancelled: type: boolean startedAt: type: string format: date-time '400': description: Cannot start job in invalid status content: application/json: schema: $ref: '#/components/schemas/Error' example: detail: Cannot start job in 'running' status '401': $ref: '#/components/responses/Unauthorized' '404': description: Batch job not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' security: - bearerAuth: [] components: schemas: Error: type: object properties: success: type: boolean example: false error: type: string example: Error message code: type: string example: ERROR_CODE 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. ````