Skip to main content
POST
/
v1
/
tasks
/
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")

task_run = client.beta.task_run.create(
    input="What was the GDP of France in 2023?",
    processor='base',
    enable_events=True,
    mcp_servers=[
        McpServerParam(
            type='url',
            name='parallel_web_search',
            url='https://mcp.parallel.ai/v1beta/search_mcp',
            headers={'x-api-key': 'API Key'}
        )
    ],
    betas=['events-sse-2025-07-24','mcp-server-2025-07-17']
)
print(task_run.run_id)
{
  "run_id": "trun_9907962f83aa4d9d98fd7f4bf745d654",
  "status": "queued",
  "is_active": true,
  "processor": "core",
  "metadata": {
    "my_key": "my_value"
  },
  "created_at": "2025-04-23T20:21:48.037943Z",
  "modified_at": "2025-04-23T20:21:48.037943Z"
}

Authorizations

​
x-api-key
string
header
required

Headers

​
parallel-beta
string | null

Body

application/json

Task run input with additional beta fields.

​
input
required

Input to the task, either text or a JSON object.

Examples:

"What was the GDP of France in 2023?"

"{\"country\": \"France\", \"year\": 2023}"

​
processor
string
required

Processor to use for the task.

Examples:

"base"

​
task_spec
object | null

Task specification. If unspecified, defaults to auto output schema. 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.

​
metadata
object | null

User-provided metadata stored with the run. Keys and values must be strings with a maximum length of 16 and 512 characters respectively.

​
source_policy
object | null

Optional source policy governing preferred and disallowed domains in web search results. Source policy for web search results.

This policy governs which sources are allowed/disallowed in results.

​
mcp_servers
McpServer · object[] | null

Optional list of MCP servers to use for the run. 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).

​
enable_events
boolean | null

Controls tracking of task run execution progress. When set to true, progress events are recorded and can be accessed via the Task Run events 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).

​
webhook
object | null

Callback URL (webhook endpoint) that will receive an HTTP POST when the run completes. This feature is not available via the Python SDK. To enable this feature in your API requests, specify the parallel-beta header with webhook-2025-08-12 value. Webhooks for Task Runs.

Response

Successful Response

Status of a task run.

​
run_id
string
required

ID of the task run.

Examples:

"trun_e0083b6aac0544eb8686e8d2a76533d2"

​
status
enum<string>
required

Status of the run.

Available options:
queued,
action_required,
running,
completed,
failed,
cancelling,
cancelled
Examples:

"queued"

"action_required"

"running"

"completed"

"failed"

"cancelling"

"cancelled"

​
is_active
boolean
required

Whether the run is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}.

​
processor
string
required

Processor used for the run.

Examples:

"base"

​
created_at
string | null
required

Timestamp of the creation of the task, as an RFC 3339 string.

Examples:

"2025-04-24T18:56:22.513132Z"

​
modified_at
string | null
required

Timestamp of the last modification to the task, as an RFC 3339 string.

Examples:

"2025-04-24T18:56:22.513132Z"

​
warnings
Warning · object[] | null

Warnings for the run, if any.

Examples:
[]
​
error
object | null

Error for the run, present only if status is 'failed'. An error message.

​
metadata
object | null

User-provided metadata stored with the run.

Examples:
{}
​
taskgroup_id
string | null

ID of the taskgroup to which the run belongs.

⌘I