openapi: 3.1.0 info: title: Parallel Chat API (Beta) Chat API (Beta) Tasks API description: Parallel API contact: name: Parallel Support url: https://parallel.ai email: support@parallel.ai version: 0.1.2 servers: - url: https://api.parallel.ai description: Parallel API security: - ApiKeyAuth: [] tags: - name: Tasks description: 'The Task API executes web research and extraction tasks. Clients submit a natural-language objective with an optional input schema; the service plans retrieval, fetches relevant URLs, and returns outputs that conform to a provided or inferred JSON schema. Supports deep research style queries and can return rich structured JSON outputs. Processors trade-off between cost, latency, and quality. Each processor supports calibrated confidences. - Output metadata: citations, excerpts, reasoning, and confidence per field Task Groups enable batch execution of many independent Task runs with group-level monitoring and failure handling. - Submit hundreds or thousands of Tasks as a single group - Observe group progress and receive results as they complete - Real-time updates via Server-Sent Events (SSE) - Add tasks to an existing group while it is running - Group-level retry and error aggregation' paths: /v1/tasks/groups: post: tags: - Tasks summary: Create Task Group description: Initiates a TaskGroup to group and track multiple runs. operationId: tasks_taskgroups_post_v1_tasks_groups_post requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateTaskGroupRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskGroupResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() task_group = client.task_group.create(metadata={"key": "value"}) print(task_group.task_group_id)' - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroup = await client.taskGroup.create({\n metadata: {'key': 'value'},\n});\nconsole.log(taskGroup.taskgroup_id);" /v1/tasks/groups/{taskgroup_id}: get: tags: - Tasks summary: Retrieve Task Group description: Retrieves aggregated status across runs in a TaskGroup. operationId: tasks_taskgroups_get_v1_tasks_groups__taskgroup_id__get parameters: - name: taskgroup_id in: path required: true schema: type: string title: Taskgroup Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskGroupResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() task_group = client.task_group.retrieve("taskgroup_id") print(task_group.status)' - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroup = await client.taskGroup.retrieve(\n 'taskgroup_id',\n);\nconsole.log(taskGroup.status);" /v1/tasks/groups/{taskgroup_id}/events: get: tags: - Tasks summary: Stream Task Group Events description: 'Streams events from a TaskGroup: status updates and run completions. The connection will remain open for up to an hour as long as at least one run in the group is still active.' operationId: tasks_sessions_events_get_v1_tasks_groups__taskgroup_id__events_get parameters: - name: taskgroup_id in: path required: true schema: type: string title: Taskgroup Id - name: last_event_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Last Event Id - name: timeout in: query required: false schema: anyOf: - type: number - type: 'null' title: Timeout responses: '200': description: Successful Response content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/TaskGroupStatusEvent' - $ref: '#/components/schemas/TaskRunEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: type mapping: task_group_status: '#/components/schemas/TaskGroupStatusEvent' task_run.state: '#/components/schemas/TaskRunEvent' error: '#/components/schemas/ErrorEvent' title: Response 200 Tasks Sessions Events Get V1 Tasks Groups Taskgroup Id Events Get example: type: task_group_status event_id: '123' status: num_task_runs: 1 task_run_status_counts: completed: 1 is_active: false status_message: '' modified_at: '2025-04-23T20:21:48.037943Z' '404': description: TaskGroup not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: TaskGroup not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group_events = client.task_group.events(\"taskgroup_id\")\nfor event in task_group_events:\n print(event)\n" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroupEvents = await client.taskGroup.events(\n 'taskgroup_id',\n);\nfor await (const event of taskGroupEvents) {\n console.log(event);\n}\n" /v1/tasks/groups/{taskgroup_id}/runs: post: tags: - Tasks summary: Add Runs to Task Group description: Initiates multiple task runs within a TaskGroup. operationId: tasks_taskgroups_runs_post_v1_tasks_groups__taskgroup_id__runs_post parameters: - name: taskgroup_id in: path required: true schema: type: string title: Taskgroup Id - name: refresh_status in: query required: false schema: type: boolean default: true title: Refresh Status - name: parallel-beta in: header required: false schema: anyOf: - type: string - type: 'null' title: Parallel-Beta x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) to enable. items: $ref: '#/components/schemas/ParallelBeta' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskGroupRunRequest' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskGroupRunResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: "from parallel import Parallel\nfrom parallel.types import McpServerParam\nfrom parallel.types.run_input_param import RunInputParam\n\nclient = Parallel(api_key=\"API Key\")\ngroup_status = client.task_group.add_runs(\n \"taskgroup_id\",\n inputs=[\n RunInputParam(\n input=\"What was the GDP of France in 2023?\",\n processor=\"base\",\n enable_events=True,\n mcp_servers=[McpServerParam(\n type=\"url\",\n name=\"parallel_web_search\",\n url=\"https://mcp.parallel.ai/v1beta/search_mcp\",\n headers={\"x-api-key\": \"API Key\"}\n )]\n )\n ]\n)\nprint(group_status.status)\n" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst groupStatus = await client.taskGroup.addRuns(\n 'taskgroup_id',\n {\n inputs: [\n {\n input: 'What was the GDP of France in 2023?',\n processor: 'base',\n enable_events: true,\n mcp_servers: [{\n type: 'url',\n name: 'parallel_web_search',\n url: 'https://mcp.parallel.ai/v1beta/search_mcp',\n headers: {'x-api-key': 'API Key'}\n }]\n }\n ]\n }\n);\nconsole.log(groupStatus.status);" get: tags: - Tasks summary: Fetch Task Group Runs description: 'Retrieves task runs in a TaskGroup and optionally their inputs and outputs. All runs within a TaskGroup are returned as a stream. To get the inputs and/or outputs back in the stream, set the corresponding `include_input` and `include_output` parameters to `true`. The stream is resumable using the `event_id` as the cursor. To resume a stream, specify the `last_event_id` parameter with the `event_id` of the last event in the stream. The stream will resume from the next event after the `last_event_id`.' operationId: tasks_taskgroups_runs_get_v1_tasks_groups__taskgroup_id__runs_get parameters: - name: taskgroup_id in: path required: true schema: type: string title: Taskgroup Id - name: last_event_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Last Event Id - name: status in: query required: false schema: anyOf: - enum: - queued - action_required - running - completed - failed - cancelling - cancelled type: string - type: 'null' title: Status - name: include_input in: query required: false schema: type: boolean default: false title: Include Input - name: include_output in: query required: false schema: type: boolean default: false title: Include Output responses: '200': description: Successful Response content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/TaskRunEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: type mapping: task_run.state: '#/components/schemas/TaskRunEvent' error: '#/components/schemas/ErrorEvent' title: Response 200 Tasks Taskgroups Runs Get V1 Tasks Groups Taskgroup Id Runs Get example: type: task_run.state event_id: '123' input: processor: core metadata: my_key: my_value input: country: France year: 2023 run: run_id: trun_9907962f83aa4d9d98fd7f4bf745d654 interaction_id: trun_9907962f83aa4d9d98fd7f4bf745d654 status: completed is_active: false processor: core metadata: my_key: my_value created_at: '2025-04-23T20:21:48.037943Z' modified_at: '2025-04-23T20:21:48.037943Z' '404': description: TaskGroup not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: TaskGroup not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\ntask_group_runs = client.task_group.get_runs(\"taskgroup_id\")\nfor run in task_group_runs:\n print(run)\n" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskGroupRuns = await client.taskGroup.getRuns(\n 'taskgroup_id',\n);\nfor await (const run of taskGroupRuns) {\n console.log(run);\n}\n" /v1/tasks/groups/{taskgroup_id}/runs/{run_id}: get: tags: - Tasks summary: Retrieve Task Group Run description: 'Retrieves run status by run_id. This endpoint is equivalent to fetching run status directly using the `retrieve()` method or the `tasks/runs` GET endpoint. The run result is available from the `/result` endpoint.' operationId: tasks_taskgroups_runs_id_get_v1_tasks_groups__taskgroup_id__runs__run_id__get parameters: - name: taskgroup_id in: path required: true schema: type: string title: Taskgroup Id - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRun' example: run_id: trun_9907962f83aa4d9d98fd7f4bf745d654 interaction_id: trun_9907962f83aa4d9d98fd7f4bf745d654 status: running 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' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run id not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() task_run = client.task_run.retrieve("run_id") print(task_run.status)' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); const taskRun = await client.taskRun.retrieve(''run_id''); console.log(taskRun.status);' /v1/tasks/runs: post: tags: - Tasks summary: Create Task Run description: 'Initiates a task run. Returns immediately with a run object in status ''queued''. Beta features can be enabled by setting the ''parallel-beta'' header.' operationId: tasks_runs_post_v1_tasks_runs_post parameters: - name: parallel-beta in: header required: false schema: anyOf: - type: string - type: 'null' title: Parallel-Beta x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) to enable. items: $ref: '#/components/schemas/ParallelBeta' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskRunInput' responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRun' example: run_id: trun_9907962f83aa4d9d98fd7f4bf745d654 interaction_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' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '402': description: 'Payment required: insufficient credit in account' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Payment required: insufficient credit in account' schema: $ref: '#/components/schemas/ErrorResponse' '403': description: 'Forbidden: invalid processor in request' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Forbidden: invalid processor in request' schema: $ref: '#/components/schemas/ErrorResponse' '422': description: 'Unprocessable content: request validation error' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unprocessable content: request validation error' schema: $ref: '#/components/schemas/ErrorResponse' '429': description: 'Too many requests: quota temporarily exceeded' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Too many requests: quota temporarily exceeded' schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\ntask_run = client.task_run.create(\n input=\"What was the GDP of France in 2023?\",\n processor=\"base\",\n)\nprint(task_run.run_id)" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst taskRun = await client.taskRun.create({\n input: 'What was the GDP of France in 2023?',\n processor: 'base',\n});\nconsole.log(taskRun.run_id);" /v1/tasks/runs/{run_id}: get: tags: - Tasks summary: Retrieve Task Run description: 'Retrieves run status by run_id. The run result is available from the `/result` endpoint.' operationId: tasks_runs_get_v1_tasks_runs__run_id__get parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRun' example: run_id: trun_9907962f83aa4d9d98fd7f4bf745d654 interaction_id: trun_9907962f83aa4d9d98fd7f4bf745d654 status: running 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' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run id not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() task_run = client.task_run.retrieve("run_id") print(task_run.status)' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); const taskRun = await client.taskRun.retrieve(''run_id''); console.log(taskRun.status);' /v1/tasks/runs/{run_id}/events: get: tags: - Tasks summary: Stream Task Run Events description: 'Streams events for a task run. Returns a stream of events showing progress updates and state changes for the task run. For task runs that did not have enable_events set to true during creation, the frequency of events will be reduced.' operationId: tasks_runs_events_get_v1_tasks_runs__run_id__events_get parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/TaskRunProgressStatsEvent' - $ref: '#/components/schemas/TaskRunProgressMessageEvent' - $ref: '#/components/schemas/TaskRunEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: type mapping: task_run.progress_stats: '#/components/schemas/TaskRunProgressStatsEvent' task_run.progress_msg.plan: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.search: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.result: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.tool_call: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.exec_status: '#/components/schemas/TaskRunProgressMessageEvent' task_run.state: '#/components/schemas/TaskRunEvent' error: '#/components/schemas/ErrorEvent' title: Response 200 Tasks Runs Events Get V1 Tasks Runs Run Id Events Get example: type: task_run.progress_msg.plan message: Planning task... timestamp: '2025-04-23T20:21:48.037943Z' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run id not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\nevents = client.task_run.events(run_id=\"run_id\")\nfor event in events:\n print(event)\n" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst events = await client.taskRun.events(\n 'run_id',\n);\nfor await (const event of events) {\n console.log(event);\n}\n" /v1/tasks/runs/{run_id}/input: get: tags: - Tasks summary: Retrieve Task Run Input description: Retrieves the input of a run by run_id. operationId: tasks_runs_input_get_v1_tasks_runs__run_id__input_get parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRunInput' example: processor: core metadata: my_key: my_value task_spec: output_schema: json_schema: type: object properties: gdp: type: string description: GDP in USD for the year, formatted like '$3.1 trillion (2023)' required: - gdp additionalProperties: false type: json input_schema: json_schema: type: object properties: country: type: string year: type: integer required: - country - year additionalProperties: false type: json input: country: France year: 2023 '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run id not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' /v1/tasks/runs/{run_id}/result: get: tags: - Tasks summary: Retrieve Task Run Result description: Retrieves a run result by run_id, blocking until the run is completed. operationId: tasks_runs_result_get_v1_tasks_runs__run_id__result_get parameters: - name: run_id in: path required: true schema: type: string title: Run Id - name: timeout in: query required: false schema: type: integer default: 600 title: Timeout - name: parallel-beta in: header required: false schema: anyOf: - type: string - type: 'null' title: Parallel-Beta x-stainless-override-schema: x-stainless-param: betas x-stainless-extend-default: true type: array description: Optional header to specify the beta version(s) to enable. items: $ref: '#/components/schemas/ParallelBeta' responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TaskRunResult' example: run: run_id: trun_9907962f83aa4d9d98fd7f4bf745d654 interaction_id: trun_9907962f83aa4d9d98fd7f4bf745d654 status: completed is_active: false processor: core metadata: my_key: my_value created_at: '2025-04-23T20:21:48.037943Z' modified_at: '2025-04-23T20:21:48.037943Z' output: basis: [] type: json content: gdp: $3.1 trillion (2023) '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run failed or run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run failed or run id not found schema: $ref: '#/components/schemas/ErrorResponse' '408': description: Request timed out; run still active content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request timed out; run still active schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: 'from parallel import Parallel client = Parallel() task_run_result = client.task_run.result(run_id="run_id") print(task_run_result.output)' - lang: TypeScript source: 'import Parallel from "parallel-web"; const client = new Parallel(); const taskRunResult = await client.taskRun.result(''run_id''); console.log(taskRunResult.output);' /v1beta/tasks/runs/{run_id}/events: get: tags: - Tasks summary: Stream Task Run Events description: 'Streams events for a task run. Returns a stream of events showing progress updates and state changes for the task run. For task runs that did not have enable_events set to true during creation, the frequency of events will be reduced.' operationId: tasks_runs_events_get_v1beta_tasks_runs__run_id__events_get parameters: - name: run_id in: path required: true schema: type: string title: Run Id responses: '200': description: Successful Response content: text/event-stream: schema: oneOf: - $ref: '#/components/schemas/TaskRunProgressStatsEvent' - $ref: '#/components/schemas/TaskRunProgressMessageEvent' - $ref: '#/components/schemas/TaskRunEvent' - $ref: '#/components/schemas/ErrorEvent' discriminator: propertyName: type mapping: task_run.progress_stats: '#/components/schemas/TaskRunProgressStatsEvent' task_run.progress_msg.plan: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.search: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.result: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.tool_call: '#/components/schemas/TaskRunProgressMessageEvent' task_run.progress_msg.exec_status: '#/components/schemas/TaskRunProgressMessageEvent' task_run.state: '#/components/schemas/TaskRunEvent' error: '#/components/schemas/ErrorEvent' title: Response 200 Tasks Runs Events Get V1Beta Tasks Runs Run Id Events Get example: type: task_run.progress_msg.plan message: Planning task... timestamp: '2025-04-23T20:21:48.037943Z' '401': description: 'Unauthorized: invalid or missing credentials' content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: 'Unauthorized: invalid or missing credentials' schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Run id not found content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Run id not found schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Request validation error content: application/json: example: type: error error: ref_id: fcb2b4f3-c75e-4186-87bc-caa1a8381331 message: Request validation error schema: $ref: '#/components/schemas/ErrorResponse' x-code-samples: - lang: Python source: "from parallel import Parallel\n\nclient = Parallel()\n\nevents = client.beta.task_run.events(run_id=\"run_id\")\nfor event in events:\n print(event)\n" - lang: TypeScript source: "import Parallel from \"parallel-web\";\n\nconst client = new Parallel();\n\nconst events = await client.beta.taskRun.events(\n 'run_id',\n);\nfor await (const event of events) {\n console.log(event);\n}\n" components: schemas: AutoSchema: properties: type: type: string const: auto title: Type description: The type of schema being defined. Always `auto`. default: auto type: object title: AutoSchema description: Auto schema for a task input or output. TaskGroupRunRequest: properties: default_task_spec: anyOf: - $ref: '#/components/schemas/TaskSpec' - type: 'null' description: Default task spec to use for the runs. If task_spec is specified in a run, it overrides this default. inputs: items: $ref: '#/components/schemas/TaskRunInput' type: array title: Inputs description: 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. type: object required: - inputs title: TaskGroupRunRequest description: Request to initiate new task runs in a task group. TaskGroupStatusEvent: properties: type: type: string const: task_group_status title: Type description: Event type; always 'task_group_status'. event_id: type: string title: Event ID description: Cursor to resume the event stream. status: $ref: '#/components/schemas/TaskGroupStatus' description: Task group status object. type: object required: - type - event_id - status title: TaskGroupStatusEvent description: Event indicating an update to group status. TaskRunProgressStatsEvent: properties: type: type: string const: task_run.progress_stats title: Type description: Event type; always 'task_run.progress_stats'. source_stats: $ref: '#/components/schemas/TaskRunSourceStats' description: Source stats describing progress so far. progress_meter: type: number title: Progress Meter description: Completion percentage of the task run. Ranges from 0 to 100 where 0 indicates no progress and 100 indicates completion. type: object required: - type - source_stats - progress_meter title: TaskRunProgressStatsEvent description: A progress update for a task run. TaskGroupStatus: properties: num_task_runs: type: integer title: Num Task Runs description: Number of task runs in the group. task_run_status_counts: additionalProperties: type: integer propertyNames: enum: - queued - action_required - running - completed - failed - cancelling - cancelled type: object title: Task Run Status Counts description: Number of task runs with each status. is_active: type: boolean title: Is Active description: True if at least one run in the group is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}. status_message: anyOf: - type: string - type: 'null' title: Status Message description: Human-readable status message for the group. modified_at: anyOf: - type: string - type: 'null' title: Modified At description: Timestamp of the last status update to the group, as an RFC 3339 string. examples: - '2025-04-24T18:56:22.513132Z' type: object required: - num_task_runs - task_run_status_counts - is_active - status_message - modified_at title: TaskGroupStatus description: Status of a task group. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError TaskRunTextOutput: properties: basis: items: $ref: '#/components/schemas/FieldBasis' type: array title: Basis description: Basis for the output. The basis has a single field 'output'. type: type: string const: text title: Type description: The type of output being returned, as determined by the output schema of the task spec. mcp_tool_calls: anyOf: - items: $ref: '#/components/schemas/McpToolCall' type: array - type: 'null' title: Mcp Tool Calls description: MCP tool calls made by the task. beta_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Beta Fields description: Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls). deprecated: true content: type: string title: Content description: Text output from the task. type: object required: - basis - type - content title: TaskRunTextOutput description: Output from a task that returns text. ParallelBeta: anyOf: - enum: - mcp-server-2025-07-17 - events-sse-2025-07-24 - webhook-2025-08-12 - findall-2025-09-15 - search-extract-2025-10-10 - field-basis-2025-11-25 type: string - type: string description: Model for the parallel-beta header. title: ParallelBeta McpServer: properties: type: type: string const: url title: Type description: Type of MCP server being configured. Always `url`. default: url url: type: string title: Url description: URL of the MCP server. headers: anyOf: - additionalProperties: type: string format: password writeOnly: true type: object - type: 'null' title: Headers description: Headers for the MCP server. name: type: string title: Name description: Name of the MCP server. allowed_tools: anyOf: - items: type: string type: array - type: 'null' title: Allowed Tools description: List of allowed tools for the MCP server. type: object required: - url - name title: McpServer description: MCP server configuration. TaskGroupResponse: properties: taskgroup_id: type: string title: Taskgroup ID description: ID of the group. metadata: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object - type: 'null' title: Metadata description: User-provided metadata stored with the group. status: $ref: '#/components/schemas/TaskGroupStatus' description: Status of the group. created_at: anyOf: - type: string - type: 'null' title: Created At description: Timestamp of the creation of the group, as an RFC 3339 string. examples: - '2025-04-24T18:56:22.513132Z' type: object required: - taskgroup_id - status - created_at title: TaskGroupResponse description: Response object for a task group, including its status and metadata. TaskRunProgressMessageEvent: properties: type: type: string enum: - task_run.progress_msg.plan - task_run.progress_msg.search - task_run.progress_msg.result - task_run.progress_msg.tool_call - task_run.progress_msg.exec_status title: Type description: Event type; always starts with 'task_run.progress_msg'. message: type: string title: Message description: Progress update message. timestamp: anyOf: - type: string - type: 'null' title: Timestamp description: Timestamp of the message. type: object required: - type - message - timestamp title: TaskRunProgressMessageEvent description: A message for a task run progress update. TaskRunInput: properties: processor: type: string title: Processor description: Processor to use for the task. examples: - base metadata: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object - type: 'null' title: Metadata description: 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: anyOf: - $ref: '#/components/schemas/SourcePolicy' - type: 'null' description: Optional source policy governing preferred and disallowed domains in web search results. advanced_settings: anyOf: - $ref: '#/components/schemas/TaskAdvancedSettings' - type: 'null' description: Advanced search configuration for the task run. task_spec: anyOf: - $ref: '#/components/schemas/TaskSpec' - type: 'null' description: Task specification. If unspecified, defaults to auto output schema. input: anyOf: - type: string - additionalProperties: true type: object title: Input description: Input to the task, either text or a JSON object. examples: - What was the GDP of France in 2023? - '{"country": "France", "year": 2023}' previous_interaction_id: anyOf: - type: string - type: 'null' title: Previous Interaction Id description: Interaction ID to use as context for this request. mcp_servers: anyOf: - items: $ref: '#/components/schemas/McpServer' type: array - type: 'null' title: Mcp Servers description: Optional list of MCP servers to use for the run. enable_events: anyOf: - type: boolean - type: 'null' title: Enable Events description: 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://docs.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). webhook: anyOf: - $ref: '#/components/schemas/Webhook' - type: 'null' description: "Callback URL (webhook endpoint) that will receive an HTTP POST when the run completes. \nThis feature is not available via the Python SDK." type: object required: - processor - input title: TaskRunInput description: Request to run a task. FieldBasis: description: Citations and reasoning supporting one field of a task output. properties: field: description: Name of the output field. title: Field type: string citations: default: [] description: List of citations supporting the output field. items: $ref: '#/components/schemas/Citation' title: Citations type: array reasoning: description: Reasoning for the output field. title: Reasoning type: string confidence: anyOf: - type: string - type: 'null' default: null description: Confidence level for the output field. Only certain processors provide confidence levels. examples: - low - medium - high title: Confidence required: - field - reasoning title: FieldBasis type: object TaskSpec: properties: output_schema: anyOf: - $ref: '#/components/schemas/JsonSchema' - $ref: '#/components/schemas/TextSchema' - $ref: '#/components/schemas/AutoSchema' - type: string title: Output Schema description: 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. input_schema: anyOf: - type: string - $ref: '#/components/schemas/JsonSchema' - $ref: '#/components/schemas/TextSchema' - type: 'null' title: Input Schema description: 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. type: object required: - output_schema title: TaskSpec description: '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.' Error: properties: ref_id: type: string title: Reference ID description: Reference ID for the error. message: type: string title: Message description: Human-readable message. detail: anyOf: - additionalProperties: true type: object - type: 'null' title: Detail description: Optional detail supporting the error. type: object required: - ref_id - message title: Error description: An error message. TaskRunResult: properties: run: $ref: '#/components/schemas/TaskRun' description: Task run object with status 'completed'. output: oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' title: Output description: Output from the task conforming to the output schema. discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' type: object required: - run - output title: TaskRunResult description: Result of a task run. Citation: description: A citation for a task output. properties: title: anyOf: - type: string - type: 'null' default: null description: Title of the citation. title: Title url: description: URL of the citation. title: Url type: string excerpts: anyOf: - items: type: string type: array - type: 'null' default: null description: Excerpts from the citation supporting the output. Only certain processors provide excerpts. title: Excerpts required: - url title: Citation type: object ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError TaskRun: properties: run_id: type: string title: Run ID description: ID of the task run. examples: - trun_e0083b6aac0544eb8686e8d2a76533d2 interaction_id: type: string title: Interaction ID description: Identifier for this interaction. Pass this value as `previous_interaction_id` to reuse context for a future request. examples: - trun_e0083b6aac0544eb8686e8d2a76533d2 status: type: string enum: - queued - action_required - running - completed - failed - cancelling - cancelled title: Status description: Status of the run. examples: - queued - action_required - running - completed - failed - cancelling - cancelled is_active: type: boolean title: Is Active description: Whether the run is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}. warnings: anyOf: - items: $ref: '#/components/schemas/Warning' type: array - type: 'null' title: Warnings description: Warnings for the run, if any. examples: - [] error: anyOf: - $ref: '#/components/schemas/Error' - type: 'null' description: Error for the run, present only if status is 'failed'. processor: type: string title: Processor description: Processor used for the run. examples: - base metadata: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object - type: 'null' title: Metadata description: User-provided metadata stored with the run. examples: - {} taskgroup_id: anyOf: - type: string - type: 'null' title: Taskgroup ID description: ID of the taskgroup to which the run belongs. created_at: anyOf: - type: string - type: 'null' title: Created At description: Timestamp of the creation of the task, as an RFC 3339 string. examples: - '2025-04-24T18:56:22.513132Z' modified_at: anyOf: - type: string - type: 'null' title: Modified At description: Timestamp of the last modification to the task, as an RFC 3339 string. examples: - '2025-04-24T18:56:22.513132Z' type: object required: - run_id - interaction_id - status - is_active - processor - created_at - modified_at title: TaskRun description: Status of a task run. Warning: properties: type: type: string enum: - spec_validation_warning - input_validation_warning - warning title: Type description: Type of warning. Note that adding new warning types is considered a backward-compatible change. examples: - spec_validation_warning - input_validation_warning message: type: string title: Message description: Human-readable message. detail: anyOf: - additionalProperties: true type: object - type: 'null' title: Detail description: Optional detail supporting the warning. type: object required: - type - message title: Warning description: Human-readable message for a task. ErrorResponse: properties: type: type: string const: error title: Type description: Always 'error'. error: $ref: '#/components/schemas/Error' description: Error. type: object required: - type - error title: ErrorResponse description: Response object used for non-200 status codes. TaskRunEvent: properties: type: type: string const: task_run.state title: Type description: Event type; always 'task_run.state'. event_id: anyOf: - type: string - type: 'null' title: Event ID description: Cursor to resume the event stream. Always empty for non Task Group runs. input: anyOf: - $ref: '#/components/schemas/TaskRunInput' - type: 'null' description: Input to the run; included only if requested. run: $ref: '#/components/schemas/TaskRun' description: Task run object. output: anyOf: - oneOf: - $ref: '#/components/schemas/TaskRunTextOutput' - $ref: '#/components/schemas/TaskRunJsonOutput' discriminator: propertyName: type mapping: json: '#/components/schemas/TaskRunJsonOutput' text: '#/components/schemas/TaskRunTextOutput' - type: 'null' title: Output description: Output from the run; included only if requested and if status == `completed`. type: object required: - type - event_id - run title: TaskRunEvent description: 'Event when a task run transitions to a non-active status. May indicate completion, cancellation, or failure.' TextSchema: properties: description: anyOf: - type: string - type: 'null' title: Description description: A text description of the desired output from the task. examples: - GDP in USD for the year, formatted like '$3.1 trillion (2023)' type: type: string const: text title: Type description: The type of schema being defined. Always `text`. default: text type: object title: TextSchema description: Text description for a task input or output. Webhook: properties: url: type: string title: Url description: URL for the webhook. event_types: items: type: string enum: - task_run.status type: array title: Event Types description: Event types to send the webhook notifications for. default: [] type: object required: - url title: Webhook description: Webhooks for Task Runs. ErrorEvent: properties: type: type: string const: error title: Type description: Event type; always 'error'. error: $ref: '#/components/schemas/Error' description: Error. type: object required: - type - error title: ErrorEvent description: Event indicating an error. CreateTaskGroupRequest: properties: metadata: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean type: object - type: 'null' title: Metadata description: User-provided metadata stored with the task group. type: object title: CreateTaskGroupRequest description: Request to create a task group. SourcePolicy: properties: include_domains: items: type: string type: array title: Include Domains description: 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). The combined number of domains in include_domains and exclude_domains cannot exceed 200. examples: - - wikipedia.org - usa.gov - .edu exclude_domains: items: type: string type: array title: Exclude Domains description: 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). The combined number of domains in include_domains and exclude_domains cannot exceed 200. examples: - - reddit.com - x.com - .ai after_date: anyOf: - type: string format: date - type: 'null' title: After Date description: 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). examples: - '2024-01-01' type: object title: SourcePolicy description: 'Source policy for web search results. This policy governs which sources are allowed/disallowed in results.' JsonSchema: properties: json_schema: additionalProperties: true type: object title: Json Schema description: A JSON Schema object. Only a subset of JSON Schema is supported. examples: - additionalProperties: false properties: gdp: description: GDP in USD for the year, formatted like '$3.1 trillion (2023)' type: string required: - gdp type: object type: type: string const: json title: Type description: The type of schema being defined. Always `json`. default: json type: object required: - json_schema title: JsonSchema description: JSON schema for a task input or output. TaskRunJsonOutput: properties: basis: items: $ref: '#/components/schemas/FieldBasis' type: array title: Basis description: 'Basis for each top-level field in the JSON output. Per-list-element basis entries are available only when the `parallel-beta: field-basis-2025-11-25` header is supplied.' type: type: string const: json title: Type description: The type of output being returned, as determined by the output schema of the task spec. mcp_tool_calls: anyOf: - items: $ref: '#/components/schemas/McpToolCall' type: array - type: 'null' title: Mcp Tool Calls description: MCP tool calls made by the task. beta_fields: anyOf: - additionalProperties: true type: object - type: 'null' title: Beta Fields description: Deprecated. mcp-server-2025-07-17 is now included directly in the output (e.g. mcp_tool_calls). deprecated: true content: additionalProperties: true type: object title: Content description: Output from the task as a native JSON object, as determined by the output schema of the task spec. output_schema: anyOf: - additionalProperties: true type: object - type: 'null' title: Output Schema description: Output schema for the Task Run. Populated only if the task was executed with an auto schema. type: object required: - basis - type - content title: TaskRunJsonOutput description: Output from a task that returns JSON. TaskRunSourceStats: properties: num_sources_considered: anyOf: - type: integer - type: 'null' title: Num Sources Considered description: Number of sources considered in processing the task. num_sources_read: anyOf: - type: integer - type: 'null' title: Num Sources Read description: Number of sources read in processing the task. sources_read_sample: anyOf: - items: type: string type: array - type: 'null' title: Sources Read Sample description: A sample of URLs of sources read in processing the task. type: object required: - num_sources_considered - num_sources_read - sources_read_sample title: TaskRunSourceStats description: Source stats for a task run. TaskAdvancedSettings: properties: location: anyOf: - type: string - type: 'null' title: Location description: ISO 3166-1 alpha-2 country code for geo-targeted search results. examples: - us - gb - de - jp type: object title: TaskAdvancedSettings description: Advanced search configuration for a task run. TaskGroupRunResponse: properties: status: $ref: '#/components/schemas/TaskGroupStatus' description: Status of the group. run_ids: items: type: string type: array title: Run IDs description: IDs of the newly created runs. run_cursor: anyOf: - type: string - type: 'null' title: Run Cursor description: Cursor for these runs in the run stream at taskgroup/runs?last_event_id=. Empty for the first runs in the group. event_cursor: anyOf: - type: string - type: 'null' title: Event Cursor description: Cursor for these runs in the event stream at taskgroup/events?last_event_id=. Empty for the first runs in the group. type: object required: - status - run_ids - run_cursor - event_cursor title: TaskGroupRunResponse description: Response from adding new task runs to a task group. McpToolCall: properties: tool_call_id: type: string title: Tool Call ID description: Identifier for the tool call. server_name: type: string title: Server Name description: Name of the MCP server. tool_name: type: string title: Tool Name description: Name of the tool being called. arguments: type: string title: Arguments description: Arguments used to call the MCP tool. content: anyOf: - type: string - type: 'null' title: Content description: Output received from the tool call, if successful. error: anyOf: - type: string - type: 'null' title: Error description: Error message if the tool call failed. type: object required: - tool_call_id - server_name - tool_name - arguments title: McpToolCall description: Result of an MCP tool call. securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key