--- title: "Create Task Run" method: POST path: "/v1/tasks/runs" tags: ["Tasks v1"] --- # Create Task Run `POST /v1/tasks/runs` Initiates a task run. Returns immediately with a run object in status 'queued'. Beta features can be enabled by setting the 'parallel-beta' header. ## Request body - TaskRunInput — Request to run a task. - `input` union, required — Input to the task, either text or a JSON object. - string - object - `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. - `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 ## Response `202` Successful Response - TaskRun — Status of a task run. - `created_at` string, nullable, required — Timestamp of the creation of the task, as an RFC 3339 string. - `error` Error — An error message. - `detail` object, nullable — Optional detail supporting the error. - `message` string, required — Human-readable message. - `ref_id` string, required — Reference ID for the error. - `is_active` boolean, required — Whether the run is currently active, i.e. status is one of {'cancelling', 'queued', 'running'}. - `metadata` object, nullable — User-provided metadata stored with the run. - `modified_at` string, nullable, required — Timestamp of the last modification to the task, as an RFC 3339 string. - `processor` string, required — Processor used for the run. - `run_id` string, required — ID of the task run. - `status` 'queued' | 'action_required' | 'running' | 'completed' | 'failed' | 'cancelling' | 'cancelled', required — Status of the run. - `taskgroup_id` string, nullable — ID of the taskgroup to which the run belongs. - `warnings` Warning[], nullable — Warnings for the run, if any. - `detail` object, nullable — Optional detail supporting the warning. - `message` string, required — Human-readable message. - `type` 'spec_validation_warning' | 'input_validation_warning' | 'warning', required — Type of warning. Note that adding new warning types is considered a backward-compatible change. ## Other responses - `401` — Unauthorized: invalid or missing credentials - `402` — Payment required: insufficient credit in account - `403` — Forbidden: invalid processor in request - `422` — Unprocessable content: request validation error - `429` — Too many requests: quota temporarily exceeded ## Changes - **2025-11-06** `a2d634b57a8e` — 2 info - api tag `Tasks v1` added - api tag `Task API v1` removed - **2025-09-15** `ed59cb6466c0` — 4 info - the request property `task_spec/anyOf[subschema #1: TaskSpec]/input_schema/anyOf[subschema #3: TextSchema]/description` became optional - the request property `task_spec/anyOf[subschema #1: TaskSpec]/output_schema/anyOf[subschema #2: TextSchema]/description` became optional - request property `task_spec/anyOf[subschema #1: TaskSpec]/input_schema/anyOf[subschema #3: TextSchema]/description` list-of-types was widened by adding types `null` to media type `application/json` - request property `task_spec/anyOf[subschema #1: TaskSpec]/output_schema/anyOf[subschema #2: TextSchema]/description` list-of-types was widened by adding types `null` to media type `application/json` - **2025-08-31** `1aeb1c81a849` — 1 breaking, 3 warning, 15 info - removed the success response with the status `200` - added the new `input_validation_warning` enum value to the `warnings/anyOf[subschema #1]/items/type` response property for the response status `202` - added the new `spec_validation_warning` enum value to the `warnings/anyOf[subschema #1]/items/type` response property for the response status `202` - added the new `warning` enum value to the `warnings/anyOf[subschema #1]/items/type` response property for the response status `202` - …15 more - …earlier changes not shown [Full history](https://skmtc.dev/parallel-web/apis/parallel-api/changes/v1/tasks/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/70ca78f3dbac/schema)