Batch Operations¶

Every service exposes a batch tool that executes up to 20 operations in a single HTTP round-trip. Instead of making N separate calls for a compound task (create a file, then set its sharing, then move it), you pack them into one request and get a single response with per-operation results.

How It Works¶

The batch endpoint on the Apps Script proxy receives an ordered array of {action, params} objects, executes them sequentially, and returns a results array - one entry per operation. Execution is strictly sequential, so operation N+1 sees the effects of operations 1 through N. If an operation fails, execution continues through the remaining operations; errors are collected alongside successes.

If any operation fails, the proxy returns top-level partial: true and top-level results. Do not treat a successful HTTP response as an atomic transaction.

POST /exec
{
  "action": "batch",
  "params": {
    "operations": [
      { "action": "someAction", "params": { ... } },
      { "action": "anotherAction", "params": { ... } },
      ...
    ]
  }
}

JSON Example¶

Request:

{
  "action": "batch",
  "token": "<proxy-token>",
  "params": {
    "operations": [
      {
        "action": "fileSearch",
        "params": { "query": "name contains 'Q4' and mimeType = 'application/pdf'" }
      },
      {
        "action": "fileCreate",
        "params": { "name": "README.md", "content": "# Q4 Docs\n\nIndex of all Q4 reports.", "mimeType": "text/markdown" }
      },
      {
        "action": "fileGetPermissions",
        "params": { "fileId": "abc123XYZ456" }
      }
    ]
  }
}

Response:

{
  "success": true,
  "data": {
    "status": "PARTIAL_SUCCESS",
    "totalOperations": 3,
    "succeeded": 2,
    "failed": 1,
    "operationWeight": 5
  },
  "partial": true,
  "results": [
    {
      "index": 0,
      "action": "fileSearch",
      "success": true,
      "data": [
        { "id": "abc123", "name": "Q4_Report.pdf", "mimeType": "application/pdf" }
      ]
    },
    {
      "index": 1,
      "action": "fileCreate",
      "success": true,
      "data": {
        "file": { "id": "xyz789", "name": "README.md", "mimeType": "text/markdown" }
      }
    },
    {
      "index": 2,
      "action": "fileGetPermissions",
      "success": false,
      "error": { "code": "NOT_FOUND", "message": "File not found: abc123XYZ456" }
    }
  ]
}

Atomicity And Retries¶

Batch operations are not atomic. A successful batch with partial: true means at least one operation mutated state and at least one operation failed.

Retry guidance:

• Include idempotencyKey inside retry-prone create, send, and share operation params when the schema supports it.
• If a batch returns partial: true, use the per-operation results to decide which operations already completed before retrying.
• If a client times out and no response is available, inspect affected resources before retrying operations that did not include idempotency keys.
• Destructive operations still require confirmation inside their operation params.

Action Name Mapping¶

The action field in each operation uses the same names as the individual tools, but in their proxy-internal camelCase form.

Drive¶

Gmail¶

Calendar¶

Sheets¶

Slides¶

Docs¶

Tasks¶

Forms¶

Error Response Format¶

Each result entry in the results array has this shape:

{
  index: number        // Zero-based operation index
  action: string       // The action name that was attempted
  success: boolean     // Whether the operation succeeded
  data?: unknown       // Present only when success is true
  error?: {            // Present only when success is false
    code: string       // Error code (UNAUTHORIZED, NOT_FOUND, BAD_REQUEST, INTERNAL_ERROR, etc.)
    message: string    // Human-readable error message
  }
}

When to Use Batch vs Individual Tools¶

Batch is most impactful for setup and formatting workflows where a large number of small mutations would otherwise create latency from sequential round-trips.

Limits¶

• Maximum 20 operations per batch. Exceeding this returns BAD_REQUEST.
• Operations execute sequentially within the batch — not in parallel.
• All operations in a batch must target the same service (there is no cross-service batching).
• A batch is charged by the sum of child operation weights against the 100 weighted units/minute per-proxy limit.