NewAnswers MCP: one question, one checked answer for your agent.See how it works

Guides

A developer's guide to Parallel's Task API

By , founder of HyperresearchUpdated

Parallel’s Task API turns a question or a row of input into web research, returned as a typed JSON object or a cited Markdown report, with a research basis of citations, reasoning and a confidence rating attached. You pick a processor per run, from lite at $5 per 1,000 runs to ultra8x at $2,400 per 1,000, and you run many rows at once through a task group. Every Parallel fact here comes from Parallel’s own docs, read on 2026-10-22. We make Hyperresearch, a vendor in the same market.

Processors set the price, the depth and the field budget

Every Task Run names a processor, and the processor fixes the price. Parallel’s pricing docs charge per run, “not per output field”, and do not bill failed runs.

Processor Price per 1,000 runs Approximate max fields
lite $5 about 2
base $10 about 5
core $25 about 10
core2x $50 about 10
pro $100 about 20
ultra $300 about 20
ultra2x $600 about 25
ultra4x $1,200 about 25
ultra8x $2,400 about 25

The field counts come from the processor guide, which calls them guidelines: five hard analytical fields can cost more capacity than fifteen simple lookups. The deep research guide says deep research is “optimized within the pro and ultra processor families”. When a caller is waiting on the answer, Parallel points you to its Responses API instead, priced at $10 to $250 per 1,000 requests.

Task groups run one spec over thousands of rows

For a large batch research job on Parallel, use the Task Group API: create a group, add up to 1,000 runs per POST under one default_task_spec, then stream the results back. A run that carries its own task_spec overrides the default. The endpoints are:

  • POST /v1/tasks/groups creates the group.
  • POST /v1/tasks/groups/{taskgroup_id}/runs adds runs.
  • GET /v1/tasks/groups/{taskgroup_id} returns is_active and task_run_status_counts.
  • GET /v1/tasks/groups/{taskgroup_id}/runs streams a snapshot of every run over SSE, with include_input and include_output; resume with last_event_id to pick up runs added later.
  • GET /v1/tasks/groups/{taskgroup_id}/events streams group status updates and run state changes.
  • GET /v1/tasks/runs/{run_id}/result returns one completed result.

The calls below follow Parallel’s cURL quickstart (read 2026-10-22), with a smaller spec and two rows. They need curl, jq and PARALLEL_API_KEY set in your shell:

Terminal window
TASK_SPEC='{
"input_schema": {"type": "json", "json_schema": {"type": "object",
"properties": {"company_name": {"type": "string"}, "company_website": {"type": "string"}},
"required": ["company_name", "company_website"]}},
"output_schema": {"type": "json", "json_schema": {"type": "object",
"properties": {"market_position": {"type": "string", "description": "Market positioning analysis"}},
"required": ["market_position"], "additionalProperties": false}}
}'
TASKGROUP_ID=$(curl -s --request POST \
--url https://api.parallel.ai/v1/tasks/groups \
--header 'Content-Type: application/json' \
--header "x-api-key: ${PARALLEL_API_KEY}" \
--data '{}' | jq -r '.taskgroup_id')
curl --request POST \
--url "https://api.parallel.ai/v1/tasks/groups/${TASKGROUP_ID}/runs?refresh_status=false" \
--header 'Content-Type: application/json' \
--header "x-api-key: ${PARALLEL_API_KEY}" \
--data '{
"default_task_spec": '"$TASK_SPEC"',
"inputs": [
{"input": {"company_name": "Acme Corp", "company_website": "https://acme.com"}, "processor": "pro"},
{"input": {"company_name": "TechStart", "company_website": "https://techstart.io"}, "processor": "pro"}
]
}'

refresh_status=false is a query parameter the docs recommend when adding runs at scale; the POST then skips the full status refresh. Two limits shape a large job. The rate limits page allows 2,000 Task Runs created per minute by default, and every item in inputs counts; polling with GET does not. And the processor guide says a large burst waits in a queue, so end-to-end time can exceed the published execution times.

Auto, text and JSON schemas return different shapes

Auto schema lets the processor design the JSON for an open research question; a structured json schema returns the fields you define on every run, which is what code downstream needs. A Task Spec’s output_schema takes one of three types, per the Task Spec docs:

  • auto: the processor designs the JSON. It enables deep research style output only on pro and above and is the default on the pro and ultra lines; the deep research guide shows an HVAC market report with 124 content fields and 610 citations.
  • text: a Markdown report “with in-line citations”. Its description steers length and content.
  • json: your JSON Schema. The root must be an object, every field should be in required, and additionalProperties should be false; make a field optional with a union such as ["string", "null"]. Limits include 5 levels of nesting, 100 properties, 15,000 characters for the spec, and 25,000 for the spec and input combined.

If you omit task_spec, the create run reference says the run “defaults to auto output schema”. Use auto when you have a question and no fixed shape. Use json when code needs the same fields every time, as in enrichment. Use text when a person reads the result.

The Basis object carries citations, reasoning and confidence for each field

Parallel’s Basis attaches citations, reasoning and a high, medium or low confidence rating to each output field: every completed result has output.content and output.basis, an array of FieldBasis objects. Per the research basis docs, each one has:

  • field: the output field, a dot path such as key_executives.0 for a list element, or output for text.
  • citations: each a url with the excerpts used.
  • reasoning: how the sources were weighed, reconciled or converted.
  • confidence: high, medium or low.

JSON outputs get an entry for each top-level field and each element of a top-level list; auto outputs get nested entries for nested fields too. The per-element entries no longer need the parallel-beta: field-basis-2025-11-25 header, which the docs say to remove as of August 24, 2026. A text output’s basis is not nested: one entry that lists citations for every site visited.

Parallel describes the ratings as calibrated. Its Basis announcement of May 2025 says calibration was tested on composite datasets of easy, medium and hard questions, that high-confidence outputs had “2-3X lower error rates” than the dataset overall, and that reviewing only low-confidence outputs cut errors by about half. Those are Parallel’s own tests. The basis records where an answer came from; the docs do not describe a separate check of each citation against the sentence it supports.

Citation coverage rises with smaller fields and per-field instructions

To get more of a Parallel deep research output cited, ask for json or auto output instead of text, keep each run under its processor’s field budget, and write each field’s description as its prompt. Parallel’s docs do not define a coverage metric; these are the levers they describe:

  1. Prefer JSON or auto over text. A text report gets one basis entry for everything; a JSON output gets one per field and per list element, and auto nests them, so each claim you care about can carry its own citations and confidence.
  2. Stay under the processor’s field budget. The processor guide says that near the limit, with quality issues, you should “try a higher-tier processor”.
  3. Write each field’s description as its prompt. The best practices page calls the description “your primary tool for controlling output quality”: name the entity, what to find, the format, preferred sources, and what to return when nothing is found. Do not add reasoning or confidence fields; the basis already has them.
  4. Constrain sources only when you must. source_policy takes include_domains or exclude_domains (domains, path prefixes or extensions such as .gov, 200 entries combined; exclusions apply only when there are no inclusions). The source policy docs warn that it “can significantly reduce result quality” and suggest steering in the objective when you only want to prefer a source.
  5. Add connectors for specialist sources. advanced_settings.data_sources takes a free list, such as ["clinical_trials", "pubmed"], and a pay_per_use list; connector results are cited in the basis like web pages (data connectors).
  6. Split and chain. The processor guide shows a base run whose output feeds a pro run. Asking for fewer fields per run, or re-running low-confidence fields at a higher processor, keeps each field inside its budget.

A field written this way, in the shape of the docs’ own examples (the null in its type lets the “return null” instruction pass validation):

"funding_date": {
"type": ["string", "null"],
"description": "Date of the latest funding round in YYYY-MM-DD format, from the company's press release or an SEC filing. If unavailable, return null."
}

Monitor events can start Task runs through webhooks

To combine Monitor with the Task API, let a Monitor webhook start a Task run: fetch the detected event, pass its output.content as the Task input, and pass its event_id as previous_interaction_id. The Monitor API watches the web on a frequency such as 1h, 1d or 1w and calls your webhook. A monitor created with POST /v1/monitors can subscribe to monitor.event.detected, monitor.execution.completed and monitor.execution.failed (Monitor webhooks). The detected payload carries an event_group_id, not the event itself.

Parallel’s follow-up tasks guide gives that chain; passing the event_id carries the event’s context into the run. The calls below follow its deep research cURL (read 2026-10-22), with one change: the request body is built with jq rather than pasted into a heredoc, so an event summary containing quotes or line breaks still makes valid JSON. MONITOR_ID and EVENT_GROUP_ID come from the webhook payload:

Terminal window
EVENT=$(curl --silent \
--url "https://api.parallel.ai/v1/monitors/${MONITOR_ID}/events?event_group_id=${EVENT_GROUP_ID}" \
--header "x-api-key: $PARALLEL_API_KEY")
OUTPUT=$(echo "$EVENT" | jq -r '.events[0].output.content')
EVENT_ID=$(echo "$EVENT" | jq -r '.events[0].event_id')
jq -n --arg out "$OUTPUT" --arg id "$EVENT_ID" '{
input: ("Research the following event in depth and summarize its strategic implications: " + $out),
processor: "ultra",
previous_interaction_id: $id
}' | curl --request POST \
--url https://api.parallel.ai/v1/tasks/runs \
--header 'Content-Type: application/json' \
--header "x-api-key: $PARALLEL_API_KEY" \
--data @-

Monitor tracks what is new from the moment it is created; for retrospective questions the docs send you to deep research. Monitor checks cost $3 per 1,000 on lite and $10 on base.

A pipeline integration rests on webhooks, metadata and stored results

To put the Task API into an enterprise data pipeline, run each batch as a task group, tag every run with your row key in metadata, take completions on a webhook into your queue, and store each result’s content and basis yourself. The pieces are in the create run reference. metadata stores your own keys on the run (keys up to 16 characters, values up to 512), so a result can be joined back to its source row. webhook takes a url and event_types: ["task_run.status"], fired when a run completes or fails, with HMAC signature verification described in Parallel’s webhook setup guide (Task webhooks). The payload is the Task Run object, with your metadata, not the output, so fetch GET /v1/tasks/runs/{run_id}/result on each completion. The reference notes webhooks are not available through the Python SDK, so set them over raw HTTP. enable_events (on by default from pro up) exposes progress at GET /v1/tasks/runs/{run_id}/events. Task group runs follow your account’s retention settings, and Zero Data Retention deployments do not keep completed run data, so persist results when they arrive. Write content and basis side by side and route low-confidence fields to review.

Parallel versus OpenAI deep research for programmatic use

For programmatic deep research, Parallel’s Task API is the more direct choice today, because OpenAI no longer has a deep research API model. OpenAI’s deprecations page lists o3-deep-research and o4-mini-deep-research as shut down on July 23, 2026, with gpt-5.6-sol, a general model, as the replacement. Deep research on OpenAI now means building the research loop yourself around that model and its web search tool; migrating off the OpenAI deep research API covers the options. Parallel offers the pieces a pipeline needs as documented features: a fixed price per run, your own JSON schema, a basis per field, task groups and webhooks. For a caller that waits on the answer, Parallel’s Responses API is “OpenAI-compatible” per its pricing docs.

Where Hyperresearch differs

Hyperresearch is a deep research API built for the case where one long report is the deliverable. A run takes a question and returns an adversarially reviewed Markdown report with every citation checked against the source it cites. A Deep run adds a verification receipt with a verdict for each checked citation: supported, partially supported, unsupported or wrong source. Every source a run reads is kept in a searchable workspace vault, and runs filed under the same project_id reuse it (runs docs). Agents can start and read runs through the remote MCP server at https://mcp.hyperresearch.ai/mcp. Pricing is flat per run: Light $9, Deep $49.

Parallel is the better fit for structured enrichment of many rows: 2,000 runs a minute by default, your schema filled field by field, and a cost per run from half a cent to $2.40. Hyperresearch does not return your schema and is not built for that volume. If you want to keep Parallel and check its citations, the citation verification API takes another tool’s output and its sources. The full comparison is at Parallel Task API vs Hyperresearch.