Skip to main content
POST
/
v1beta
/
tasks
/
groups
/
{taskgroup_id}
/
runs
from parallel import Parallel from parallel.types.beta import McpServerParam from parallel.types.beta.beta_run_input_param import BetaRunInputParam client = Parallel(api_key="API Key") group_status = client.beta.task_group.add_runs( "taskgroup_id", inputs=[ BetaRunInputParam( input="What was the GDP of France in 2023?", processor="base", mcp_servers=[McpServerParam( type="url", name="parallel_web_search", url="https://mcp.parallel.ai/v1beta/search_mcp", headers={"x-api-key": "API Key"} )] ) ], betas=["mcp-server-2025-07-17"] ) print(group_status.status) 
{
  "status": {
    "num_task_runs": 123,
    "task_run_status_counts": {},
    "is_active": true,
    "status_message": "<string>",
    "modified_at": "2025-04-24T18:56:22.513132Z"
  },
  "run_ids": [
    "<string>"
  ],
  "run_cursor": "<string>",
  "event_cursor": "<string>"
}

Authorizations

​
x-api-key
string
header
required

Headers

​
parallel-beta
string | null

Path Parameters

​
taskgroup_id
string
required

Query Parameters

​
refresh_status
boolean
default:true

When set to true (default), the response includes the latest status of the runs. Set to false to skip status refresh and just add runs to the queue, which is useful when adding tasks to a task group at scale.

Body

application/json

Request to initiate new task runs in a task group.

​
inputs
TaskRunInput · object[]
required

List of task runs to execute. Up to 1,000 runs can be specified per request. If you'd like to add more runs, split them across multiple TaskGroup POST requests.

​
default_task_spec
TaskSpec · object

Default task spec to use for the runs. If task_spec is specified in a run, it overrides this default.

​
refresh_status
boolean
default:true

Whether to refresh and return the latest status of all runs in the response. Defaults to true. Set to false when adding tasks at scale to get faster responses. The response will include a cached status instead. You can retrieve the latest status separately via the GET task-group endpoint.

Response

Successful Response

Response from adding new task runs to a task group.

​
status
TaskGroupStatus · object
required

Status of the group. When refresh_status is true (the default), this returns the latest status. When refresh_status is false, this returns a cached status.

​
run_ids
string[]
required

IDs of the newly created runs.

​
run_cursor
string | null
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.

​
event_cursor
string | null
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.