> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maxicore.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Batch AI processing with job queues in Maxi AI Core
> Submit multiple text or image generation prompts as a background job, poll for progress, and retrieve results without blocking your AI session.
Batch processing lets your AI agent submit dozens or hundreds of prompts in a single call and retrieve the results when they are ready — without waiting for each individual generation to complete. Jobs run in the background via WP Cron: you get back a job ID immediately, then poll `maxi/get-job-status` to track progress and collect output as each item finishes. This is a Pro plan feature.
Batch abilities require a Pro license and a configured API key for your chosen provider. See [Managing AI provider credentials](/security/credentials). Also ensure WP Cron is running on your server — batch jobs do not process if WP Cron is blocked or disabled.
Batch processing depends on WP Cron. If your server disables WP Cron (`define( 'DISABLE_WP_CRON', true )`), jobs will queue but never execute. Use a real server cron job that hits `wp-cron.php` on a regular schedule, or re-enable WP Cron for batch processing to work reliably.
## Submit a text batch
Call `maxi/generate-text-ai-batch` with an array of prompts. Each prompt is processed as a separate item in the job.
```json theme={null}
{
"prompts": [
"Write a product description for a standing desk",
"Write a product description for an ergonomic chair",
"Write a product description for a monitor arm"
],
"provider": "openai",
"model": "gpt-4o-mini"
}
```
The response returns a job ID immediately:
```json theme={null}
{
"success": true,
"data": {
"job_id": 42
}
}
```
## Submit an image batch
Call `maxi/generate-image-ai-batch` with an array of prompts. Each image is generated and sideloaded into the WordPress media library as it completes.
```json theme={null}
{
"prompts": [
"Product photo of a standing desk",
"Lifestyle photo of a home office"
],
"provider": "openai"
}
```
The response includes a job ID. Use `maxi/get-job-status` to track progress and retrieve the attachment IDs as each image finishes.
## Full batch workflow
Call `maxi/generate-text-ai-batch` or `maxi/generate-image-ai-batch` with your array of prompts and the target provider. You receive a `job_id` in the response.
```json theme={null}
{
"prompts": [
"Write a product description for a standing desk",
"Write a product description for an ergonomic chair"
],
"provider": "openai",
"model": "gpt-4o-mini"
}
```
Call `maxi/get-job-status` with the job ID to check progress. Poll at a reasonable interval — every 10 to 30 seconds is usually sufficient.
```json theme={null}
{
"job_id": 42
}
```
The response includes overall status and per-item progress:
```json theme={null}
{
"success": true,
"data": {
"job_id": 42,
"status": "running",
"total_items": 3,
"processed_items": 1,
"failed_items": 0,
"items": [
{
"index": 0,
"status": "completed",
"output": "The ErgoRise standing desk combines..."
},
{
"index": 1,
"status": "pending",
"output": null
},
{
"index": 2,
"status": "pending",
"output": null
}
]
}
}
```
Continue polling until `status` is `completed`, `failed`, or `cancelled`. When the job is complete, every item's `output` field contains its generated content (for text) or an attachment ID (for images).
| Job status | Meaning |
| ----------- | ------------------------------------------------------ |
| `pending` | Job is queued, not yet started |
| `running` | Items are being processed |
| `completed` | All items finished (some may have failed individually) |
| `failed` | The job itself failed before completing |
| `cancelled` | The job was cancelled via `maxi/cancel-job` |
## Cancel a job
Call `maxi/cancel-job` to stop a job that is pending or running. Items already completed are not rolled back — only unstarted items are skipped.
```json theme={null}
{
"job_id": 42
}
```
## Configure retry behavior
When an individual item fails — for example, due to a provider rate limit or transient error — the job retries it automatically with exponential backoff. You can tune this behavior via `maxi/update-ai-settings`:
| Setting field | Default | Description |
| --------------------- | ------- | --------------------------------------------------------------- |
| `batch_max_attempts` | `3` | Maximum retry attempts per item before marking it failed |
| `retry_delay_seconds` | `5` | Base delay between retries (doubles on each subsequent attempt) |
```json theme={null}
{
"batch_max_attempts": 5,
"retry_delay_seconds": 10
}
```
For large batches against rate-limited providers, increase `retry_delay_seconds` to reduce the chance of repeated failures on the same item. Check `maxi/get-ai-settings` to see your current retry configuration.
## Related abilities
Generate a single piece of text synchronously — returns content immediately without job polling.
Generate or edit a single image synchronously — result is sideloaded and returned as an attachment ID.
Set and rotate API keys for all supported AI providers. Required before making any generation call.
Configure default providers per capability and tune retry and batch worker settings.