---
title: "Add Runs to Task Group"
method: POST
path: "/v1beta/tasks/groups/{taskgroup_id}/runs"
tags: ["Tasks (Beta)"]
---

# Add Runs to Task Group

`POST /v1beta/tasks/groups/{taskgroup_id}/runs`

Initiates multiple task runs within a TaskGroup.

## Path parameters

- `taskgroup_id` string, required

## Headers

- `parallel-beta` string, nullable

## Request body

- TaskGroupRunRequest — Request to initiate new task runs in a task group.
  - `default_task_spec` TaskSpec — Specification for a task. Auto output schemas can be specified by setting `output_schema={"type":"auto"}`. Not specifying a TaskSpec is the same as setting an auto output schema. For convenience bare strings are also accepted as input or output schemas.
    - `input_schema` union — Optional JSON schema or text description of expected input to the task. A bare string is equivalent to a text schema with the same description.
      - string
      - JsonSchema — JSON schema for a task input or output.
        - `json_schema` object, required — A JSON Schema object. Only a subset of JSON Schema is supported.
        - `type` 'json' — The type of schema being defined. Always `json`.
      - TextSchema — Text description for a task input or output.
        - `description` string, nullable — A text description of the desired output from the task.
        - `type` 'text' — The type of schema being defined. Always `text`.
    - `output_schema` union, required — JSON schema or text fully describing the desired output from the task. Descriptions of output fields will determine the form and content of the response. A bare string is equivalent to a text schema with the same description.
      - JsonSchema — JSON schema for a task input or output.
        - `json_schema` object, required — A JSON Schema object. Only a subset of JSON Schema is supported.
        - `type` 'json' — The type of schema being defined. Always `json`.
      - TextSchema — Text description for a task input or output.
        - `description` string, nullable — A text description of the desired output from the task.
        - `type` 'text' — The type of schema being defined. Always `text`.
      - AutoSchema — Auto schema for a task input or output.
        - `type` 'auto' — The type of schema being defined. Always `auto`.
      - string
  - `inputs` BetaTaskRunInput[], required — List of task runs to execute.
    - `enable_events` boolean, nullable — Controls tracking of task run execution progress. When set to true, progress events are recorded and can be accessed via the [Task Run events](https://platform.parallel.ai/api-reference) endpoint. When false, no progress events are tracked. Note that progress tracking cannot be enabled after a run has been created. The flag is set to true by default for premium processors (pro and above). To enable this feature in your requests, specify `events-sse-2025-07-24` as one of the values in `parallel-beta` header (for API calls) or `betas` param (for the SDKs).
    - `input` union, required — Input to the task, either text or a JSON object.
      - string
      - object
    - `mcp_servers` McpServer[], nullable — Optional list of MCP servers to use for the run. To enable this feature in your requests, specify `mcp-server-2025-07-17` as one of the values in `parallel-beta` header (for API calls) or `betas` param (for the SDKs).
      - `allowed_tools` string[], nullable — List of allowed tools for the MCP server.
      - `headers` object, nullable — Headers for the MCP server.
      - `name` string, required — Name of the MCP server.
      - `type` 'url' — Type of MCP server being configured. Always `url`.
      - `url` string, required — URL of the MCP server.
    - `metadata` object, nullable — User-provided metadata stored with the run. Keys and values must be strings with a maximum length of 16 and 512 characters respectively.
    - `processor` string, required — Processor to use for the task.
    - `source_policy` SourcePolicy — Source policy for web search results. This policy governs which sources are allowed/disallowed in results.
      - `after_date` string, date, nullable — Optional start date for filtering search results. Results will be limited to content published on or after this date. Provided as an RFC 3339 date string (YYYY-MM-DD).
      - `exclude_domains` string[] — List of domains to exclude from results. If specified, sources from these domains will be excluded. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk).
      - `include_domains` string[] — List of domains to restrict the results to. If specified, only sources from these domains will be included. Accepts plain domains (e.g., example.com, subdomain.example.gov) or bare domain extension starting with a period (e.g., .gov, .edu, .co.uk).
    - `task_spec` TaskSpec — Specification for a task. Auto output schemas can be specified by setting `output_schema={"type":"auto"}`. Not specifying a TaskSpec is the same as setting an auto output schema. For convenience bare strings are also accepted as input or output schemas.
      - `input_schema` union — Optional JSON schema or text description of expected input to the task. A bare string is equivalent to a text schema with the same description.
        - string
        - JsonSchema — JSON schema for a task input or output.
          - `json_schema` object, required — A JSON Schema object. Only a subset of JSON Schema is supported.
          - `type` 'json' — The type of schema being defined. Always `json`.
        - TextSchema — Text description for a task input or output.
          - `description` string, nullable — A text description of the desired output from the task.
          - `type` 'text' — The type of schema being defined. Always `text`.
      - `output_schema` union, required — JSON schema or text fully describing the desired output from the task. Descriptions of output fields will determine the form and content of the response. A bare string is equivalent to a text schema with the same description.
        - JsonSchema — JSON schema for a task input or output.
          - `json_schema` object, required — A JSON Schema object. Only a subset of JSON Schema is supported.
          - `type` 'json' — The type of schema being defined. Always `json`.
        - TextSchema — Text description for a task input or output.
          - `description` string, nullable — A text description of the desired output from the task.
          - `type` 'text' — The type of schema being defined. Always `text`.
        - AutoSchema — Auto schema for a task input or output.
          - `type` 'auto' — The type of schema being defined. Always `auto`.
        - string
    - `webhook` Webhook — Webhooks for Task Runs.
      - `event_types` string[] — Event types to send the webhook notifications for.
      - `url` string, required — URL for the webhook.

## Response `200`

Successful Response

- TaskGroupRunResponse — Response from adding new task runs to a task group.
  - `event_cursor` string, nullable, required — Cursor for these runs in the event stream at taskgroup/events?last_event_id=<event_cursor>. Empty for the first runs in the group.
  - `run_cursor` string, nullable, required — Cursor for these runs in the run stream at taskgroup/runs?last_event_id=<run_cursor>. Empty for the first runs in the group.
  - `run_ids` string[], required — IDs of the newly created runs.
  - `status` TaskGroupStatus, required — Status of a task group.
    - `is_active` boolean, required — True if at least one run in the group is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}.
    - `modified_at` string, nullable, required — Timestamp of the last status update to the group, as an RFC 3339 string.
    - `num_task_runs` integer, required — Number of task runs in the group.
    - `status_message` string, nullable, required — Human-readable status message for the group.
    - `task_run_status_counts` object, required — Number of task runs with each status.

## Other responses

- `422` — Validation Error

## Changes

- **2026-01-13** `105d778ad64d` — 12 breaking, 7 info
  - removed the enum value `auto` of the request property `default_task_spec/anyOf[subschema #1: TaskSpec]/output_schema/anyOf[subschema #3: AutoSchema]/type`
  - removed the enum value `auto` of the request property `inputs/items/task_spec/anyOf[subschema #1: TaskSpec]/output_schema/anyOf[subschema #3: AutoSchema]/type`
  - removed the enum value `json` of the request property `default_task_spec/anyOf[subschema #1: TaskSpec]/input_schema/anyOf[subschema #2: JsonSchema]/type`
  - removed the enum value `json` of the request property `default_task_spec/anyOf[subschema #1: TaskSpec]/output_schema/anyOf[subschema #1: JsonSchema]/type`
  - …15 more
- **2025-11-06** `a2d634b57a8e` — 2 info
  - api tag `Tasks (Beta)` added
  - api tag `Task API (Beta)` removed
- **2025-10-21** `e853fc79f3b4` — 1 info
  - the `` request property const value `task_run.status` was removed
- …earlier changes not shown

[Full history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1beta/tasks/groups/:taskgroup_id/runs/post.md)

---

[API](https://skmtc.dev/parallel-web/apis/parallel-api.md) · [All operations](https://skmtc.dev/parallel-web/apis/parallel-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/parallel-web/parallel-api/revisions/31ff2f5e2e00/schema)