​
Task Spec

A Task Specification (Task Spec) is a declarative template that defines the structure and requirements for the outputs of a web research operation. While optional in each Task Run, Task Specs provide significant advantages when you need precise control over your research data. Task Specs ensure consistent results by enforcing a specific output structure across multiple runs. They validate schema against expected formats and create reusable templates for common research patterns. By defining the expected outputs clearly, they also serve as self-documentation for your tasks, making them easier to understand and maintain.
ComponentRequiredPurposeFormat
Output SchemaYesDefines the structure and fields of the task resultJSON Schema or Text
Input SchemaNoSpecifies expected input parameters and their formatsJSON Schema or Text

​
Task Spec Structure

A Task Spec consists of:
FieldTypeRequiredDescription
outputSchema object or stringYesDescription and structure of the desired output
inputSchema object or stringNoDescription and structure of input parameters
When providing a bare string for input or output, it’s equivalent to a text schema with that string as the description.

​
Schema Types

Task Spec supports three schema formats:
When using the Python SDK, the Parallel Task API also supports Pydantic objects in Task Spec
auto mode enables Deep Research style outputs only in processors Pro and above. Read more about Deep Research here. 
{
  "json_schema": {
    "type": "object",
    "properties": {
      "population": {
        "type": "string",
        "description": "Current population with year of estimate"
      },
      "area": {
        "type": "string",
        "description": "Total area in square kilometers and square miles"
      }
    },
    "required": ["population", "area"]
  },
  "type": "json"
}

​
Task Spec Best Practices

Define what entity you’re researching (input) and what specific data points you need back (output). Keep both as flat-structured as possible. Our system handles complexity and instructions in the description fields for inputs and outputs. Adjusting description fields is akin to ‘prompt engineering’ for the Task Spec.
1

Identify what schema your use case requires

  • If executing a Deep Research style Task, use the Task Spec with auto schema
  • If control and specificity with regards to outputs are required, use Task Spec with a JSONSchema for inputs and outputs
  • In other cases, the Task Spec may not be necessary; the system in this case will output a plain text response
2

Define effective inputs

  • When using only text based inputs, be as specific as possible about what you are expecting the system to return. Include any instructions and preferences in the input text.
  • When using JSON Schema inputs, use the minimum fields required to uniquely identify the entity you want to enrich. For example, include both the company_name and company_website, or both the person_name and social_url, to help the system disambiguate.
  • Avoid deeply nested structures and keep the input schema flat
3

Define effective outputs (relevant when using JSONSchema outputs)

  • Include all instructions and preferences under field-level description where possible
  • Write effective description fields by using this format: Entity (what are you researching), Action (what do you want to find), Specifics (constraints, time periods, formatting requirements), and Error Handling (eg. if unavailable, return “Not Available”).
  • Use clear, descriptive field names
    • Use ceo_name instead of name
    • Use headquarters_address** instead of address
    • Use annual_revenue_2024** instead of revenue
  • Specify Data Formats
    • Always specify format for dates: YYYY-MM-DD
    • Use ranges for numerical values with units: revenue_in_millions, employee_count
    • Specify quantities for lists: top_5_products, recent_3_acquisitions
  • Unnecessary Fields: Don’t include fields like reasoning or confidence_score as these are already included in the basis
4

Additional instructions

If there are additional requirements or instructions separate from individual fields, the top-level description field is available. For example:
{
  "type": "object",
  "description": "Extract all information only from well-known government sites.",
  "properties": {
    "latest_funding_amount": {
      "type": "string",
      "description": "Funding amount in millions USD format (e.g., '50M'). If unavailable, return null."
    },
    "funding_round_type": {
      "type": "string",
      "description": "Type of funding round (Series A, Series B, etc.). If unknown, return 'Type unknown'."
    },
    "funding_date": {
      "type": "string",
      "description": "Date of funding round in YYYY-MM-DD format. If partial date available, use YYYY-MM or YYYY."
    },
    "current_employee_count": {
      "type": "string",
      "description": "Current number of employees as approximate number or range. Allow estimates when precise counts unavailable."
    }
  }
}

​
Output Schema Validation Rules

The Task API enforces several restrictions on output schemas to ensure compatibility and performance:

​
Schema Structure Rules

RuleTypeDescription
Root type must be objecterrorThe root schema must have "type": "object"
Root must have propertieserrorThe root object must have a properties field
Root cannot use anyOferrorThe root level cannot use anyOf
Standalone null typeerrornull type is only allowed in union types or anyOf
All fields must be requiredwarningAll properties should be listed in the required array
additionalProperties must be falsewarningAll object types should set additionalProperties: false
While all fields must be required in the schema, you can create optional parameters by using a union type with null. For example, "type": ["string", "null"] allows a field to be either a string or null, effectively making it optional while maintaining schema compliance.

​
Size and Complexity Limits

RuleTypeLimitDescription
Nesting deptherror5 levelsMaximum nesting depth of objects and arrays
Total propertieserror100Maximum total number of properties across all levels
Total string lengtherror15,000 charsMaximum total string length for names and values
Enum valueserror500Maximum number of enum values across all properties
Large enum string lengtherror7,500 charsMaximum string length for enums with >250 values
Task spec sizeerror10,000 charsMaximum length of the task specification
Total sizeerror15,000 charsMaximum combined length of task specification and input data

​
Unsupported Keywords

The following JSON Schema keywords are not supported in output schemas: contains, format, maxContains, maxItems, maxLength, maxProperties, maximum, minContains, minItems, minLength, minimum, minProperties, multipleOf, pattern, patternProperties, propertyNames, uniqueItems, unevaluatedItems, unevaluatedProperties irements: it has an object root type with properties, all fields are required, and additionalProperties is set to false.

​
Common Schema Errors to Avoid

Here are examples of common schema errors and how to fix them: 
{
  "type": "array",  // Error: Root type must be "object"
  "items": {
    "type": "object",
    "properties": {
      "name": { "type": "string" }
    }
  }
}
Fix: Change the root type to “object” and move array properties to a field:
{
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" }
        },
        "required": ["name"]
      }
    }
  },
  "required": ["items"],
  "additionalProperties": false
}