BatchedGridWorkflow
Overview
BatchedGridWorkflow pairs each agent inagent_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.
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 > 1reruns the same pairs, and agents retain memory across loops - One result set per loop: the response’s
outputsis 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 intasks 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.- Shell (curl)
- Python (requests)
- JavaScript (fetch)
- Go
- Rust
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.- Python
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
200withstatus: "partial", and each failed agent’s slot inoutputsis{"error": "<ExceptionType>: <message>"}instead of its output. The run is billed as usual: every agent’s tokens pluscost_per_agentfor every agent, including the failed ones. - If every agent fails, the request returns
502and nothing is charged. - If
agent_completionsortasksis missing, the two differ in length, or agent construction fails, the whole request fails with a single400before any agent runs, and nothing is charged. Thedetailof a run-time error starts with"BatchedGridWorkflowCompletionError: ".
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 > 1when 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
- Independent jobs that each need their own configuration and billing record: use Batch Agent Completions
- Sequential dependencies: use SequentialWorkflow
- Independent parallel tasks within one swarm: use ConcurrentWorkflow
- Task routing: use MultiAgentRouter
- Consensus decisions: use MajorityVoting
Design Recommendations
- Match array lengths first: build
agent_completionsandtaskstogether so they never drift out of sync - 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
- Temperature Settings: use lower temperatures (0.3-0.5) for analytical tasks, higher (0.6-0.8) for creative tasks
- Iterative Refinement: use
max_loops > 1when quality improvement from an agent revisiting its own memory is worth the added cost - Result Processing: iterate
outputsby 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-5orgpt-5.4for quality, a smaller model such asgpt-5.4-minifor cost-sensitive runs) - Monitor token usage and adjust prompt verbosity
- Remember
max_loopsmultiplies output tokens roughly linearly — amax_loops=3run costs about 3x the output tokens ofmax_loops=1
Error Handling
The API returns standard HTTP status codes:- 200: Success;
statusis"partial"if some agents failed - 400: Bad request —
agent_completionsortasksmissing, a length mismatch, invalid agent configuration (e.g. a missingagent_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_completionsortaskshas more than 50 entries,max_loopsis outside 1-50, orimgsis a non-empty list - 502: Every agent failed; nothing was charged
- 500: Server error
Related Workflows
- Batch Agent Completions - For independent jobs, each with its own configuration
- SequentialWorkflow - For step-by-step processing
- ConcurrentWorkflow - For parallel independent tasks
- MixtureOfAgents - For combining diverse specialists
- MajorityVoting - For consensus-based decisions