Batch Operations

Operations affecting more than 200 sites are automatically queued for background processing. This prevents timeouts and provides progress monitoring for large operations.

What You’ll Learn

Understanding batch thresholds and affected abilities
Reading immediate vs. queued response patterns
Monitoring batch job status
Handling errors in batch operations

Batch Threshold

The default threshold is 200 sites. Operations below this threshold execute synchronously and return results immediately.

// Default: 200 sites
$threshold = apply_filters( 'mainwp_abilities_batch_threshold', 200 );

Affected Abilities

These abilities support batch queuing:

Ability	Description
`mainwp/sync-sites-v1`	Sync multiple sites
`mainwp/run-updates-v1`	Execute updates across sites
`mainwp/update-all-v1`	Apply all updates
`mainwp/reconnect-sites-v1`	Batch reconnect
`mainwp/disconnect-sites-v1`	Batch disconnect
`mainwp/check-sites-v1`	Batch connectivity check
`mainwp/suspend-sites-v1`	Batch suspend

Update Confirmation and Permissions

In MainWP Dashboard 6.3, preview run-updates-v1 and update-all-v1 with dry_run: true, then submit the reviewed selection with confirm: true. A preview does not queue an update job. See Updates Abilities for confirmation flags and update holds. Queued jobs run under the requesting user’s permissions. MainWP rechecks site access, operation permissions, and applicable update holds before executing updates. If access changes after a job is queued, review its errors and skipped items before retrying. Check individual results even when a job’s status is completed.

Response Patterns

Immediate Response (≤200 sites)

{
  "queued": false,
  "synced": [
    {"id": 1, "url": "https://example.com", "name": "Site 1"}
  ],
  "errors": [],
  "total_synced": 1,
  "total_errors": 0
}

Queued Response (>200 sites)

{
  "queued": true,
  "job_id": "sync_abc123def456",
  "status_url": "https://your-dashboard.com/wp-json/mainwp/v2/jobs/sync_abc123def456",
  "sites_queued": 350
}

mainwp/get-batch-job-status-v1

Retrieves the current status of a queued batch operation. Method: GET (readonly)

curl -G -u "admin:xxxx" \
  --data-urlencode 'input_json={"job_id":"sync_abc123def456"}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-batch-job-status-v1/run"

Input Parameters

Name	Type	Required	Description
`job_id`	string	Yes	Job ID from queued operation

Response

{
  "job_id": "sync_abc123def456",
  "type": "sync",
  "status": "processing",
  "progress": 45,
  "processed": 90,
  "total": 200,
  "succeeded": 88,
  "failed": 2,
  "started_at": "2024-01-15T10:30:00Z",
  "completed_at": null,
  "errors": [
    {
      "site_id": 15,
      "code": "mainwp_site_offline",
      "message": "Site is unreachable"
    }
  ]
}

Status Values

Status	Description
`queued`	Waiting to start
`processing`	Currently running
`completed`	Processing finished; individual items may have failed
`failed`	Failed with errors

Polling Workflow

#!/bin/bash

# 1. Start the operation
RESPONSE=$(curl -s -X POST -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"site_ids_or_domains":[]}}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/sync-sites-v1/run")

# 2. Check if queued
QUEUED=$(echo $RESPONSE | jq -r '.queued // false')
JOB_ID=$(echo $RESPONSE | jq -r '.job_id // empty')

if [ "$QUEUED" = "true" ] && [ -n "$JOB_ID" ]; then
  echo "Job queued: $JOB_ID"

  # 3. Poll for status
  while true; do
    STATUS=$(curl -s -G -u "admin:xxxx" \
      --data-urlencode "input_json=$(jq -cn --arg job_id "$JOB_ID" '{job_id: $job_id}')" \
      "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-batch-job-status-v1/run")

    PROGRESS=$(echo $STATUS | jq -r '.progress')
    STATE=$(echo $STATUS | jq -r '.status')
    SUCCEEDED=$(echo $STATUS | jq -r '.succeeded')
    FAILED=$(echo $STATUS | jq -r '.failed')

    echo "Progress: $PROGRESS% - Status: $STATE - Succeeded: $SUCCEEDED - Failed: $FAILED"

    if [ "$STATE" = "completed" ] || [ "$STATE" = "failed" ]; then
      echo "Job finished with status: $STATE"
      echo $STATUS | jq '.errors'
      break
    fi

    sleep 10
  done
else
  echo "Executed immediately"
  echo $RESPONSE | jq '.'
fi

Job Lifecycle

Property	Value	Description
TTL	24 hours	Jobs expire after completion
Timeout	4 hours	Maximum runtime
Chunk Size	20 sites	Sites processed per cron run
Reschedule Delay	30 seconds	Delay between chunks

Error Handling

When a batch job encounters errors, individual failures are recorded while the job continues processing remaining items. Check the errors array in the status response for details:

{
  "errors": [
    {
      "site_id": 15,
      "code": "mainwp_site_offline",
      "message": "Site is unreachable"
    },
    {
      "site_id": 23,
      "code": "mainwp_child_version_outdated",
      "message": "MainWP Child plugin needs update"
    }
  ]
}

Jobs with errors complete with status: "completed" if any operations succeeded, or status: "failed" if all operations failed.

Abilities API Overview - API basics and authentication
Sites Abilities - Site management abilities
Updates Abilities - Update management abilities

Getting Started

Understanding MainWP

Dashboard

Sites

Users

Updates

Plugins

Themes

Content Operations

Clients

MCP Server

API Reference

Troubleshooting

Customization

Advanced

Resources

What You’ll Learn

Batch Threshold

Affected Abilities

Update Confirmation and Permissions

Response Patterns

Immediate Response (≤200 sites)

Queued Response (>200 sites)

mainwp/get-batch-job-status-v1

Input Parameters

Response

Status Values

Polling Workflow

Job Lifecycle

Error Handling

​What You’ll Learn

​Batch Threshold

​Affected Abilities

​Update Confirmation and Permissions

​Response Patterns

​Immediate Response (≤200 sites)

​Queued Response (>200 sites)

​mainwp/get-batch-job-status-v1

​Input Parameters

​Response

​Status Values

​Polling Workflow

​Job Lifecycle

​Error Handling

​Related Resources

What You’ll Learn

Batch Threshold

Affected Abilities

Update Confirmation and Permissions

Response Patterns

Immediate Response (≤200 sites)

Queued Response (>200 sites)

mainwp/get-batch-job-status-v1

Input Parameters

Response

Status Values

Polling Workflow

Job Lifecycle

Error Handling

Related Resources