Create Task Run

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": "<string>",
  "status": "queued",
  "is_active": true,
  "processor": "<string>",
  "created_at": "2025-04-24T18:56:22.513132Z",
  "modified_at": "2025-04-24T18:56:22.513132Z",
  "warnings": [],
  "error": {
    "ref_id": "<string>",
    "message": "<string>",
    "detail": {}
  },
  "metadata": {},
  "taskgroup_id": "<string>"
}

POST

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": "<string>",
  "status": "queued",
  "is_active": true,
  "processor": "<string>",
  "created_at": "2025-04-24T18:56:22.513132Z",
  "modified_at": "2025-04-24T18:56:22.513132Z",
  "warnings": [],
  "error": {
    "ref_id": "<string>",
    "message": "<string>",
    "detail": {}
  },
  "metadata": {},
  "taskgroup_id": "<string>"
}

Authorizations

x-api-key

string

header

required

Headers

parallel-beta

string | null

Body

application/json

Task run input with additional beta fields.

processor

string

required

Processor to use for the task.

input

required

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

Example:

"What was the GDP of France in 2023?"

metadata

Metadata · object

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

Show child attributes

metadata.{key}

source_policy

SourcePolicy · object

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

Show child attributes

source_policy.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).

source_policy.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).

task_spec

TaskSpec · object

Task specification. If unspecified, defaults to auto output schema.

Show child attributes

task_spec.output_schema

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.

Show child attributes

task_spec.output_schema.json_schema

Json Schema · object

required

A JSON Schema object. Only a subset of JSON Schema is supported.

task_spec.output_schema.type

string

default:json

The type of schema being defined. Always json.

Allowed value: "json"

task_spec.input_schema

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.

mcp_servers

McpServer · object[] | null

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).

Show child attributes

mcp_servers.url

string

required

URL of the MCP server.

mcp_servers.name

string

required

Name of the MCP server.

mcp_servers.type

string

default:url

Type of MCP server being configured. Always url.

Allowed value: "url"

mcp_servers.headers

Headers · object

Headers for the MCP server.

Show child attributes

mcp_servers.headers.{key}

string<password>

mcp_servers.allowed_tools

string[] | null

List of allowed tools for the MCP server.

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

Webhook · object

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.

Show child attributes

webhook.url

string

required

URL for the webhook.

webhook.event_types

enum<string>[]

Event types to send the webhook notifications for.

Available options:

task_run.status

Response

Successful Response

Status of a task run.

run_id

string

required

ID of the task run.

status

enum<string>

required

Status of the run.

Available options:

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.

created_at

string | null

required

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

Example:

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

modified_at

string | null

required

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

Example:

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

warnings

Warning · object[] | null

Warnings for the run, if any.

Show child attributes

warnings.type

enum<string>

required

Type of warning. Note that adding new warning types is considered a backward-compatible change.

Available options:

spec_validation_warning,

input_validation_warning,

warning

warnings.message

string

required

Human-readable message.

warnings.detail

Detail · object

Optional detail supporting the warning.

Example:

[]

error

Error · object

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

Show child attributes

error.ref_id

string

required

Reference ID for the error.

error.message

string

required

Human-readable message.

error.detail

Detail · object

Optional detail supporting the error.

metadata

Metadata · object

User-provided metadata stored with the run.

Show child attributes

metadata.{key}

Example:

{}

taskgroup_id

string | null

ID of the taskgroup to which the run belongs.

List Events Retrieve Task Run

⌘I

Extract (Beta)

Search (Beta)

Monitor

Tasks v1

Tasks (Beta)

FindAll API (Beta)

Authorizations

Headers

Body

Response