> ## Documentation Index > Fetch the complete documentation index at: https://docs.swarms.ai/llms.txt > Use this file to discover all available pages before exploring further. # Execute Batched Grid Workflow > Execute a batched grid workflow enabling parallel execution of multiple agents across multiple tasks in a single request. This is a premium-only feature. ## OpenAPI ````yaml https://api.swarms.world/openapi.json post /v1/batched-grid-workflow/completions openapi: 3.1.0 info: title: Swarms API description: >- Swarms API provides scalable, secure orchestration for multi-agent systems. Access robust endpoints for managing agents and swarms, automating workflows, and monitoring execution. Requires an API key—see the [API Keys page](https://swarms.world/platform/api-keys). Refer to [Swarms API Documentation](https://docs.swarms.ai) for guides and details. version: 1.0.0 servers: - url: https://api.swarms.world description: Swarms Production API security: [] paths: /v1/batched-grid-workflow/completions: post: tags: - Batched Grid Workflow summary: Execute Batched Grid Workflow description: >- Execute a batched grid workflow enabling parallel execution of multiple agents across multiple tasks in a single request. This is a premium-only feature. operationId: run_batched_grid_workflow_v1_batched_grid_workflow_completions_post parameters: - name: x-api-key in: header required: true schema: type: string title: X-Api-Key requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BatchedGridWorkflowInput' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/BatchedGridWorkflowOutput' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' components: schemas: BatchedGridWorkflowInput: properties: name: anyOf: - type: string - type: 'null' title: Name description: The name of the batched grid workflow. description: anyOf: - type: string - type: 'null' title: Description description: The description of the batched grid workflow. agent_completions: anyOf: - items: $ref: '#/components/schemas/AgentSpec-Input' description: The configuration of the agent to be completed. type: array maxItems: 50 - type: 'null' title: Agent Completions description: The agent completions to be completed by the batched grid workflow. tasks: anyOf: - items: type: string type: array maxItems: 50 - type: 'null' title: Tasks description: The tasks to be completed by the batched grid workflow. max_loops: anyOf: - type: integer maximum: 50 minimum: 1 - type: 'null' title: Max Loops description: >- The maximum number of loops to be completed by the batched grid workflow. At most 50. default: 1 imgs: anyOf: - items: type: string type: array - type: 'null' title: Imgs description: The images to be used by the batched grid workflow. type: object title: BatchedGridWorkflowInput BatchedGridWorkflowOutput: properties: job_id: type: string title: Job Id description: The job ID of the batched grid workflow. name: type: string title: Name description: The name of the batched grid workflow. description: type: string title: Description description: The description of the batched grid workflow. status: type: string title: Status description: The status of the batched grid workflow. outputs: title: Outputs description: The outputs of the batched grid workflow. usage: $ref: '#/components/schemas/Usage' description: The usage of the batched grid workflow. timestamp: type: string title: Timestamp description: The timestamp of the batched grid workflow. type: object required: - job_id - name - description - status - outputs - usage - timestamp title: BatchedGridWorkflowOutput HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError AgentSpec-Input: properties: agent_name: anyOf: - type: string - type: 'null' title: Agent Name description: >- The unique name assigned to the agent, which identifies its role and functionality within the swarm. description: anyOf: - type: string - type: 'null' title: Description description: >- A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform. system_prompt: anyOf: - type: string - type: 'null' title: System Prompt description: >- The initial instruction or context provided to the agent, guiding its behavior and responses during execution. marketplace_prompt_id: anyOf: - type: string - type: 'null' title: Marketplace Prompt Id description: >- The ID of a prompt from the Swarms marketplace to use as the system prompt. If provided, the prompt will be automatically retrieved from the marketplace. model_name: anyOf: - type: string - type: 'null' title: Model Name description: >- The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-5.4, claude-sonnet-5, openrouter/moonshotai/kimi-k3 default: claude-sonnet-5 fallback_models: anyOf: - items: type: string type: array - type: 'null' title: Fallback Models description: >- An ordered list of models to try if the primary model errors: the request is retried with the next model on failure. If set while model_name is omitted, the first entry becomes the primary model. Example: ['claude-sonnet-5', 'gpt-5.4']. fallback_model_name: anyOf: - type: string - type: 'null' title: Fallback Model Name description: >- A single fallback model to try if the primary model fails, tried after any `fallback_models`. Example: 'openrouter/deepseek/deepseek-v4.1-flash'. auto_generate_prompt: anyOf: - type: boolean - type: 'null' title: Auto Generate Prompt description: >- A flag indicating whether the agent should automatically create prompts based on the task requirements. default: false max_tokens: anyOf: - type: integer minimum: 1 - type: 'null' title: Max Tokens description: >- The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length. Must be at least 1. default: 16000 temperature: anyOf: - type: number maximum: 2 minimum: 0 - type: 'null' title: Temperature description: >- A parameter that controls the randomness of the agent's output; lower values result in more deterministic responses. Accepted range: 0 to 2. If omitted, no temperature is sent to the model (the provider's own default applies). role: anyOf: - type: string - type: 'null' title: Role description: >- The designated role of the agent within the swarm, which influences its behavior and interaction with other agents. default: worker max_loops: anyOf: - type: integer - type: string - type: 'null' title: Max Loops description: >- Maximum number of iterations the agent can perform for its task. Accepts an integer from 1 to 50 for a fixed count, or 'auto' to allow the system to determine the necessary number based on the task's complexity. default: 1 tools_list_dictionary: anyOf: - items: additionalProperties: true type: object type: array - type: 'null' title: Tools List Dictionary description: A dictionary of tools that the agent can use to complete its task. selected_tools: anyOf: - type: string - items: type: string type: array - type: 'null' title: Selected Tools description: >- Tools to enable for the autonomous looper when max_loops='auto'. Pass a list of tool names to restrict which tools the agent can use, or omit to allow all safe defaults. Available tools: create_plan, think, subtask_done, complete_task, respond_to_user, create_file, update_file, read_file, list_directory, delete_file, create_sub_agent, assign_task. Note: run_bash is not permitted. mcp_url: anyOf: - type: string - $ref: '#/components/schemas/MCPConnection' - additionalProperties: true type: object - type: 'null' title: Mcp Url description: >- The MCP server the agent can use to complete its task. A URL string for an unauthenticated server, or a connection object configuring auth and transport. streaming_on: anyOf: - type: boolean - type: 'null' title: Streaming On description: A flag indicating whether the agent should stream its output. default: false llm_args: anyOf: - additionalProperties: true type: object - type: 'null' title: Llm Args description: >- Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc. top_p: anyOf: - type: number - type: 'null' title: Top P description: The top_p parameter to pass to the LLM. dynamic_temperature_enabled: anyOf: - type: boolean - type: 'null' title: Dynamic Temperature Enabled description: >- A flag indicating whether the agent should dynamically adjust its temperature based on the task. default: false mcp_config: anyOf: - $ref: '#/components/schemas/MCPConnection' - additionalProperties: true type: object - type: 'null' title: Mcp Config description: The MCP connection to use for the agent. mcp_configs: anyOf: - items: anyOf: - $ref: '#/components/schemas/MCPConnection' - additionalProperties: true type: object type: array - type: 'null' title: Mcp Configs description: >- The MCP connections to use for the agent. This is a list of MCP connections. Includes multiple MCP connections. mcp_urls: anyOf: - items: anyOf: - type: string - $ref: '#/components/schemas/MCPConnection' - additionalProperties: true type: object type: array - type: 'null' title: Mcp Urls description: >- Several MCP servers for the agent. Each entry is a URL string for an unauthenticated server, or a connection object configuring auth and transport. Tools from every server are combined. tool_call_summary: anyOf: - type: boolean - type: 'null' title: Tool Call Summary description: A parameter enabling an agent to summarize tool calls. default: true reasoning_effort: anyOf: - type: string enum: - minimal - low - medium - high - none - xhigh - ultra - max - None - type: 'null' title: Reasoning Effort description: >- How much effort the agent puts into reasoning. Accepted values, tracking the reasoning levels the installed litellm advertises: 'minimal', 'low', 'medium', 'high', 'none', 'xhigh', 'ultra', 'max', 'None'. 'max' is the top tier (deepest reasoning) and no beta header is required. At 'xhigh' and above, pair with a large max_tokens so the model has room to think and answer. thinking_tokens: anyOf: - type: integer - type: 'null' title: Thinking Tokens description: The number of tokens to use for thinking. reasoning_enabled: anyOf: - type: boolean - type: 'null' title: Reasoning Enabled description: A parameter enabling an agent to use reasoning. default: false publish_to_marketplace: anyOf: - type: boolean - type: 'null' title: Publish To Marketplace description: >- A flag indicating whether to publish this agent to the Swarms marketplace. default: false use_cases: anyOf: - items: additionalProperties: type: string type: object type: array - type: 'null' title: Use Cases description: >- A list of use case dictionaries with 'title' and 'description' keys. Required when publish_to_marketplace is True. tags: anyOf: - items: type: string type: array - type: 'null' title: Tags description: >- A list of searchable tags/keywords for the marketplace (e.g., ['finance', 'analysis']). capabilities: anyOf: - items: type: string type: array - type: 'null' title: Capabilities description: >- A list of agent capabilities or features (e.g., ['trend-analysis', 'risk-assessment']). category: anyOf: - type: string - type: 'null' title: Category description: >- The marketplace category for the agent (e.g., 'research', 'content', 'coding', 'finance', 'healthcare', 'education', 'legal'). is_free: anyOf: - type: boolean - type: 'null' title: Is Free description: >- A flag indicating whether the agent is free to use in the marketplace. default: true price_usd: anyOf: - type: number - type: 'null' title: Price Usd description: >- The price in USD for using this agent in the marketplace (if not free). handoffs: anyOf: - items: $ref: '#/components/schemas/AgentSpec-Input' type: array maxItems: 2000 - type: 'null' title: Handoffs description: >- A list of agent specifications that this agent can hand off tasks to. These agents will be created and passed to the agent's handoffs parameter. At most 2000. type: object title: AgentSpec Usage: properties: input_tokens: type: integer title: Input Tokens description: The number of input tokens. output_tokens: type: integer title: Output Tokens description: The number of output tokens. total_tokens: type: integer title: Total Tokens description: The total number of tokens. total_cost: type: number title: Total Cost description: The cost in credits for the tokens. cost_per_agent: type: number title: Cost Per Agent description: The cost in credits for the agents. default: 0.01 type: object required: - input_tokens - output_tokens - total_tokens - total_cost title: Usage description: Usage statistics for the workflow execution. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError MCPConnection: properties: type: anyOf: - type: string - type: 'null' title: Type description: The type of connection, defaults to 'mcp' default: mcp url: anyOf: - type: string - type: 'null' title: Url description: The URL endpoint for the MCP server default: http://localhost:8000/mcp name: anyOf: - type: string - type: 'null' title: Name description: Human readable name for the server, used in logs and tool routing tool_configurations: anyOf: - additionalProperties: true type: object - type: 'null' title: Tool Configurations description: Dictionary containing configuration settings for MCP tools authorization_token: anyOf: - type: string - type: 'null' title: Authorization Token description: Bearer token for accessing the MCP server api_key: anyOf: - type: string - type: 'null' title: Api Key description: >- API key for the MCP server. Sent using api_key_header/api_key_prefix. api_key_header: type: string title: Api Key Header description: >- Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'. default: Authorization api_key_prefix: anyOf: - type: string - type: 'null' title: Api Key Prefix description: Prefix prepended to the API key value. Set to None/'' for raw keys. default: Bearer auth_type: anyOf: - type: string enum: - none - api_key - bearer - oauth - custom - type: 'null' title: Auth Type description: Explicit auth mode. Inferred from the other fields when omitted. oauth: anyOf: - $ref: '#/components/schemas/MCPOAuthConfig' - type: 'null' description: OAuth 2.1 configuration for this server. transport: anyOf: - type: string - type: 'null' title: Transport description: 'Transport protocol: ''streamable_http'', ''sse'', ''stdio'', or ''auto''' default: streamable_http headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Headers description: Headers to send to the MCP server timeout: anyOf: - type: integer - type: 'null' title: Timeout description: Request timeout for the MCP server default: 30 sse_read_timeout: anyOf: - type: integer - type: 'null' title: Sse Read Timeout description: How long to wait for streamed events before giving up default: 300 tool_timeout: anyOf: - type: integer - type: 'null' title: Tool Timeout description: >- How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests. default: 120 command: anyOf: - type: string - type: 'null' title: Command description: Executable to launch for the 'stdio' transport args: anyOf: - items: type: string type: array - type: 'null' title: Args description: Arguments passed to the 'stdio' command env: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Env description: Environment variables for the 'stdio' command additionalProperties: true type: object title: MCPConnection MCPOAuthConfig: properties: grant_type: type: string enum: - authorization_code - client_credentials title: Grant Type description: OAuth grant to use when no static access_token is supplied. default: authorization_code client_id: anyOf: - type: string - type: 'null' title: Client Id description: >- OAuth client id. Optional for authorization_code when the server supports dynamic client registration. client_secret: anyOf: - type: string - type: 'null' title: Client Secret description: OAuth client secret. Required for client_credentials. scopes: anyOf: - items: type: string type: array - type: 'null' title: Scopes description: Scopes to request, e.g. ['mcp:tools', 'offline_access']. redirect_uri: type: string title: Redirect Uri description: Loopback redirect URI used to capture the authorization code. default: http://127.0.0.1:8765/callback client_name: type: string title: Client Name description: Client name sent during dynamic client registration. default: Swarms Agent client_uri: anyOf: - type: string - type: 'null' title: Client Uri description: Client homepage sent during dynamic client registration. authorization_url: anyOf: - type: string - type: 'null' title: Authorization Url description: >- Explicit authorization endpoint. Discovered automatically when omitted. token_url: anyOf: - type: string - type: 'null' title: Token Url description: Explicit token endpoint. Discovered automatically when omitted. access_token: anyOf: - type: string - type: 'null' title: Access Token description: Pre-obtained access token. When set, no OAuth flow is performed. refresh_token: anyOf: - type: string - type: 'null' title: Refresh Token description: Pre-obtained refresh token, paired with access_token. token_storage_path: anyOf: - type: string - type: 'null' title: Token Storage Path description: >- File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/.json. use_token_cache: type: boolean title: Use Token Cache description: Persist tokens to disk so the browser flow is only run once. default: true open_browser: type: boolean title: Open Browser description: >- Open the system browser for the authorization step. When False the URL is logged instead. default: true callback_timeout: type: integer title: Callback Timeout description: Seconds to wait for the user to complete the browser flow. default: 300 additionalProperties: true type: object title: MCPOAuthConfig description: >- OAuth 2.1 configuration for an MCP server. Three flavours are supported: 1. ``grant_type="authorization_code"`` (default) — the interactive browser flow described by the MCP authorization spec. PKCE and RFC 7591 dynamic client registration are handled by the MCP SDK, so ``client_id`` is optional. Tokens are cached on disk so the browser prompt only happens once. 2. ``grant_type="client_credentials"`` — a headless machine-to-machine flow. Requires ``client_id``/``client_secret``. The token endpoint is discovered from the server's ``/.well-known/oauth-authorization-server`` metadata unless ``token_url`` is given. 3. ``access_token=...`` — a token you already obtained elsewhere. No flow is run; the token is simply sent as a bearer credential. Any string field may use ``"env:MY_VAR"`` or ``"${MY_VAR}"`` to read the value from the environment instead of hardcoding a secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.