Skip to main content
Swarm Type: BatchedGridWorkflow
Premium Tier Required: The /v1/batched-grid-workflow/completions endpoint is restricted to Pro, Ultra, and Premium plan subscribers. Free tier users will receive a 403 error. Upgrade your account to access batched grid workflow capabilities.

Overview

BatchedGridWorkflow pairs each agent in agent_completions with the task at the same index in tasks — agent_completions[0] runs tasks[0], agent_completions[1] runs tasks[1], and so on. All pairs run concurrently. This is not a full agent × task matrix: an agent never sees any task other than the one at its own index.
agent_completions and tasks must be the same length. A request where the two arrays differ in length fails with a 400 before any agent runs. Both arrays also accept at most 50 entries (the same limit used by /v1/swarm/batch/completions).
To have several agents look at the same input — the “multiple experts review one thing” use case — repeat the identical task string once per agent in tasks. That’s what the example below does: three analysts, three identical task strings, one shared subject. max_loops reruns the same agent/task pairs for that many iterations, reusing the same agent instances across loops. Because each agent keeps its own conversation memory between calls, later loops can build on what that agent said earlier — this is how iterative refinement works here, not a larger grid. Key features:
  • Index-paired execution: agent i always runs task i, never another agent’s task
  • Concurrent execution: all pairs for a given loop run in parallel
  • Iterative refinement: max_loops > 1 reruns the same pairs, and agents retain memory across loops
  • One result set per loop: the response’s outputs is a list with one entry per loop, each entry mapping every agent’s name to its output for that loop

Architecture

Each agent only ever runs the task paired with it by index. Repeating the same task string across every entry in tasks is what makes multiple agents analyze the same subject.

Use Cases

  • Multiple independent agent/task jobs dispatched and billed as one request (same idea as /v1/agent/batch/completions, but with built-in support for repeated, memory-carrying refinement loops)
  • Multi-perspective analysis: several specialist agents reviewing the same input (repeat the task string per agent)
  • Iterative refinement: one agent revising its own answer to the same task over several loops, using its own memory of earlier loops
  • A/B testing different agent configurations against identical input

API Usage

Basic BatchedGridWorkflow Example

Three analysts, each paired with the same task string, so every agent reviews the same subject from its own angle.
Example Response (one entry in outputs because max_loops is 1; all three agents reviewed the same repeated task string):

Advanced Example: Multi-Loop Refinement

Same agent, same task, run for three loops. Because the agent instance is reused across loops and keeps its own conversation memory, each loop can build on what it wrote before.
To refine several different topics in parallel, issue one request per topic (looping client-side), repeating that topic’s task string across every agent in the request. A single request only ever pairs each agent with one task per loop.

Request Schema

BatchedGridWorkflowInput

AgentSpec

Response Schema

BatchedGridWorkflowOutput

Usage Object

Pricing

BatchedGridWorkflow bills $0.01 per agent plus each agent’s provider-reported tokens, priced at that agent’s own model plus a 15% service fee. No night-time discount applies. For detailed pricing information, see the Pricing page.

Partial Failures

A failed agent is reported in place. The other agents’ outputs are still returned:
  • If one or more agents fail (e.g. a provider error), the response is a 200 with status: "partial", and each failed agent’s slot in outputs is {"error": "<ExceptionType>: <message>"} instead of its output. The run is billed as usual: every agent’s tokens plus cost_per_agent for every agent, including the failed ones.
  • If every agent fails, the request returns 502 and nothing is charged.
  • If agent_completions or tasks is missing, the two differ in length, or agent construction fails, the whole request fails with a single 400 before any agent runs, and nothing is charged. The detail of a run-time error starts with "BatchedGridWorkflowCompletionError: ".
One of two agents failed:
Every agent failed (HTTP 502):
Check status (or each slot for an error key) before using outputs.

Best Practices

When to Use BatchedGridWorkflow

  • Multi-perspective analysis: several specialist agents reviewing the same input (repeat the task string per agent)
  • Iterative refinement: max_loops > 1 when an agent should revise its own answer using memory of earlier loops
  • A/B testing: comparing different agent configurations against identical input
  • Paired dispatch: N independent agent/task jobs in one request

When to Use Other Endpoints

Design Recommendations

  1. Match array lengths first: build agent_completions and tasks together so they never drift out of sync
  2. Repeat task strings deliberately: duplicate a task string across every agent when you want a shared-subject comparison; use distinct strings when you want independent paired jobs
  3. Temperature Settings: use lower temperatures (0.3-0.5) for analytical tasks, higher (0.6-0.8) for creative tasks
  4. Iterative Refinement: use max_loops > 1 when quality improvement from an agent revisiting its own memory is worth the added cost
  5. Result Processing: iterate outputs by loop index, not by task index

Cost Optimization

  • Start with a small agent/task pair count to test your workflow before scaling to 50
  • Use appropriate models (claude-sonnet-5 or gpt-5.4 for quality, a smaller model such as gpt-5.4-mini for cost-sensitive runs)
  • Monitor token usage and adjust prompt verbosity
  • Remember max_loops multiplies output tokens roughly linearly — a max_loops=3 run costs about 3x the output tokens of max_loops=1

Error Handling

The API returns standard HTTP status codes:
  • 200: Success; status is "partial" if some agents failed
  • 400: Bad request — agent_completions or tasks missing, a length mismatch, invalid agent configuration (e.g. a missing agent_name), or a failure during workflow execution
  • 401: Unauthorized (invalid API key)
  • 402: Payment required (insufficient credits)
  • 403: Forbidden (account is not on a premium tier)
  • 422: Validation error — agent_completions or tasks has more than 50 entries, max_loops is outside 1-50, or imgs is a non-empty list
  • 502: Every agent failed; nothing was charged
  • 500: Server error
Example error response for a length mismatch: