---
title: "Execute Batch Agent Completions"
method: POST
path: "/v1/agent/batch/completions"
tags: ["Agents", "Batch Processing"]
---

# Execute Batch Agent Completions

`POST /v1/agent/batch/completions`

Execute multiple agent completions concurrently using optimized thread pool execution. This is a premium-only feature.

## Headers

- `x-api-key` string, required

## Request body

- AgentCompletion[]
  - `agent_config` AgentSpecInput, required
    - `agent_name` string, nullable — The unique name assigned to the agent, which identifies its role and functionality within the swarm.
    - `description` string, nullable — A detailed explanation of the agent's purpose, capabilities, and any specific tasks it is designed to perform.
    - `system_prompt` string, nullable — The initial instruction or context provided to the agent, guiding its behavior and responses during execution.
    - `marketplace_prompt_id` string, nullable — 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` string, nullable — The name of the AI model that the agent will utilize for processing tasks and generating outputs. For example: gpt-4o, gpt-4.1, openai/o3-mini
    - `fallback_models` string[], nullable — 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: ['gpt-4.1', 'gpt-5.4'].
    - `fallback_model_name` string, nullable — A single fallback model to try if the primary model fails, tried after any `fallback_models`. Example: 'gpt-4.1'.
    - `auto_generate_prompt` boolean, nullable — A flag indicating whether the agent should automatically create prompts based on the task requirements.
    - `max_tokens` integer, nullable — The maximum number of tokens that the agent is allowed to generate in its responses, limiting output length.
    - `temperature` number, nullable — 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` string, nullable — The designated role of the agent within the swarm, which influences its behavior and interaction with other agents.
    - `max_loops` union — Maximum number of iterations the agent can perform for its task. Accepts an integer for a fixed count, or 'auto' to allow the system to determine the necessary number based on the task's complexity.
      - integer
      - string
    - `tools_list_dictionary` object[], nullable — A dictionary of tools that the agent can use to complete its task.
    - `selected_tools` union — 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.
      - string
      - string[]
    - `mcp_url` string, nullable — The URL of the MCP server that the agent can use to complete its task.
    - `streaming_on` boolean, nullable — A flag indicating whether the agent should stream its output.
    - `llm_args` object, nullable — Additional arguments to pass to the LLM such as top_p, frequency_penalty, presence_penalty, etc.
    - `top_p` number, nullable — The top_p parameter to pass to the LLM.
    - `dynamic_temperature_enabled` boolean, nullable — A flag indicating whether the agent should dynamically adjust its temperature based on the task.
    - `mcp_config` MCPConnection
      - `type` string, nullable — The type of connection, defaults to 'mcp'
      - `url` string, nullable — The URL endpoint for the MCP server
      - `name` string, nullable — Human readable name for the server, used in logs and tool routing
      - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
      - `authorization_token` string, nullable — Bearer token for accessing the MCP server
      - `api_key` string, nullable — API key for the MCP server. Sent using api_key_header/api_key_prefix.
      - `api_key_header` string — Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'.
      - `api_key_prefix` string, nullable — Prefix prepended to the API key value. Set to None/'' for raw keys.
      - `auth_type` 'none' | 'api_key' | 'bearer' | 'oauth' | 'custom', nullable — Explicit auth mode. Inferred from the other fields when omitted.
      - `oauth` MCPOAuthConfig — 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.
        - `grant_type` 'authorization_code' | 'client_credentials' — OAuth grant to use when no static access_token is supplied.
        - `client_id` string, nullable — OAuth client id. Optional for authorization_code when the server supports dynamic client registration.
        - `client_secret` string, nullable — OAuth client secret. Required for client_credentials.
        - `scopes` string[], nullable — Scopes to request, e.g. ['mcp:tools', 'offline_access'].
        - `redirect_uri` string — Loopback redirect URI used to capture the authorization code.
        - `client_name` string — Client name sent during dynamic client registration.
        - `client_uri` string, nullable — Client homepage sent during dynamic client registration.
        - `authorization_url` string, nullable — Explicit authorization endpoint. Discovered automatically when omitted.
        - `token_url` string, nullable — Explicit token endpoint. Discovered automatically when omitted.
        - `access_token` string, nullable — Pre-obtained access token. When set, no OAuth flow is performed.
        - `refresh_token` string, nullable — Pre-obtained refresh token, paired with access_token.
        - `token_storage_path` string, nullable — File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/<server>.json.
        - `use_token_cache` boolean — Persist tokens to disk so the browser flow is only run once.
        - `open_browser` boolean — Open the system browser for the authorization step. When False the URL is logged instead.
        - `callback_timeout` integer — Seconds to wait for the user to complete the browser flow.
      - `transport` string, nullable — Transport protocol: 'streamable_http', 'sse', 'stdio', or 'auto'
      - `headers` object, nullable — Headers to send to the MCP server
      - `timeout` integer, nullable — Request timeout for the MCP server
      - `sse_read_timeout` integer, nullable — How long to wait for streamed events before giving up
      - `tool_timeout` integer, nullable — How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests.
      - `command` string, nullable — Executable to launch for the 'stdio' transport
      - `args` string[], nullable — Arguments passed to the 'stdio' command
      - `env` object, nullable — Environment variables for the 'stdio' command
    - `mcp_configs` MultipleMCPConnections
      - `connections` MCPConnection[], required — List of MCP connections
        - `type` string, nullable — The type of connection, defaults to 'mcp'
        - `url` string, nullable — The URL endpoint for the MCP server
        - `name` string, nullable — Human readable name for the server, used in logs and tool routing
        - `tool_configurations` object, nullable — Dictionary containing configuration settings for MCP tools
        - `authorization_token` string, nullable — Bearer token for accessing the MCP server
        - `api_key` string, nullable — API key for the MCP server. Sent using api_key_header/api_key_prefix.
        - `api_key_header` string — Header used to send the API key, e.g. 'Authorization' or 'X-API-Key'.
        - `api_key_prefix` string, nullable — Prefix prepended to the API key value. Set to None/'' for raw keys.
        - `auth_type` 'none' | 'api_key' | 'bearer' | 'oauth' | 'custom', nullable — Explicit auth mode. Inferred from the other fields when omitted.
        - `oauth` MCPOAuthConfig — 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.
          - `grant_type` 'authorization_code' | 'client_credentials' — OAuth grant to use when no static access_token is supplied.
          - `client_id` string, nullable — OAuth client id. Optional for authorization_code when the server supports dynamic client registration.
          - `client_secret` string, nullable — OAuth client secret. Required for client_credentials.
          - `scopes` string[], nullable — Scopes to request, e.g. ['mcp:tools', 'offline_access'].
          - `redirect_uri` string — Loopback redirect URI used to capture the authorization code.
          - `client_name` string — Client name sent during dynamic client registration.
          - `client_uri` string, nullable — Client homepage sent during dynamic client registration.
          - `authorization_url` string, nullable — Explicit authorization endpoint. Discovered automatically when omitted.
          - `token_url` string, nullable — Explicit token endpoint. Discovered automatically when omitted.
          - `access_token` string, nullable — Pre-obtained access token. When set, no OAuth flow is performed.
          - `refresh_token` string, nullable — Pre-obtained refresh token, paired with access_token.
          - `token_storage_path` string, nullable — File used to cache OAuth tokens. Defaults to ~/.swarms/mcp_auth/<server>.json.
          - `use_token_cache` boolean — Persist tokens to disk so the browser flow is only run once.
          - `open_browser` boolean — Open the system browser for the authorization step. When False the URL is logged instead.
          - `callback_timeout` integer — Seconds to wait for the user to complete the browser flow.
        - `transport` string, nullable — Transport protocol: 'streamable_http', 'sse', 'stdio', or 'auto'
        - `headers` object, nullable — Headers to send to the MCP server
        - `timeout` integer, nullable — Request timeout for the MCP server
        - `sse_read_timeout` integer, nullable — How long to wait for streamed events before giving up
        - `tool_timeout` integer, nullable — How long a single tool call may run before timing out. Separate from `timeout`, which bounds HTTP requests.
        - `command` string, nullable — Executable to launch for the 'stdio' transport
        - `args` string[], nullable — Arguments passed to the 'stdio' command
        - `env` object, nullable — Environment variables for the 'stdio' command
    - `tool_call_summary` boolean, nullable — A parameter enabling an agent to summarize tool calls.
    - `reasoning_effort` 'minimal' | 'low' | 'medium' | 'high' | 'none' | 'xhigh' | 'ultra' | 'max', nullable — 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'. '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` integer, nullable — The number of tokens to use for thinking.
    - `reasoning_enabled` boolean, nullable — A parameter enabling an agent to use reasoning.
    - `publish_to_marketplace` boolean, nullable — A flag indicating whether to publish this agent to the Swarms marketplace.
    - `use_cases` object[], nullable — A list of use case dictionaries with 'title' and 'description' keys. Required when publish_to_marketplace is True.
    - `tags` string[], nullable — A list of searchable tags/keywords for the marketplace (e.g., ['finance', 'analysis']).
    - `capabilities` string[], nullable — A list of agent capabilities or features (e.g., ['trend-analysis', 'risk-assessment']).
    - `category` string, nullable — The marketplace category for the agent (e.g., 'research', 'content', 'coding', 'finance', 'healthcare', 'education', 'legal').
    - `is_free` boolean, nullable — A flag indicating whether the agent is free to use in the marketplace.
    - `price_usd` number, nullable — The price in USD for using this agent in the marketplace (if not free).
    - `handoffs` AgentSpecInput[], nullable — 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.
  - `task` string, nullable — The task to be completed by the agent.
  - `history` union — The history of the agent's previous tasks and responses. Can be either a dictionary or a list of message objects.
    - object
    - object[]
  - `img` string, nullable — A base64 encoded image for the agent to process. Encode your image file to base64 and pass it here.
  - `imgs` string[], nullable — A list of base64 encoded images for the agent to process. Encode your image files to base64 and pass them here.
  - `tools_enabled` string[], nullable — A list of tools that the agent should use to complete its task.

## Response `200`

Successful Response

- AgentBatchCompletionResponse
  - `batch_id` string, nullable — The unique identifier for the agent batch completion.
  - `total_requests` integer, nullable — The total number of requests in the batch.
  - `results` unknown
  - `execution_time` number, nullable — The execution time of the agent batch completion.
  - `timestamp` string, nullable — The timestamp when the agent batch completion was created.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/swarms/apis/swarms-api.md) · [All operations](https://skmtc.net/swarms/apis/swarms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/swarms/swarms-api/versions/2575bd7539ca/schema)