Skip to main content
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:
AbilityDescription
mainwp/sync-sites-v1Sync multiple sites
mainwp/run-updates-v1Execute updates across sites
mainwp/update-all-v1Apply all updates
mainwp/reconnect-sites-v1Batch reconnect
mainwp/disconnect-sites-v1Batch disconnect
mainwp/check-sites-v1Batch connectivity check
mainwp/suspend-sites-v1Batch suspend

​
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: POST 
curl -X POST -u "admin:xxxx" \
  -H "Content-Type: application/json" \
  -d '{"input":{"job_id":"sync_abc123def456"}}' \
  "https://your-dashboard.com/wp-json/wp-abilities/v1/abilities/mainwp/get-batch-job-status-v1/run"

​
Input Parameters

NameTypeRequiredDescription
job_idstringYesJob 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

StatusDescription
queuedWaiting to start
processingCurrently running
completedFinished successfully
failedFailed 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 -X POST -u "admin:xxxx" \
      -H "Content-Type: application/json" \
      -d "{\"input\":{\"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

PropertyValueDescription
TTL24 hoursJobs expire after completion
Timeout4 hoursMaximum runtime
Chunk Size20 sitesSites processed per cron run
Reschedule Delay30 secondsDelay 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.