# A developer's guide to Parallel's Task API

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](https://docs.parallel.ai/getting-started/pricing) 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](https://docs.parallel.ai/task-api/guides/choose-a-processor), which calls them guidelines: five hard analytical fields can cost more capacity than fifteen simple lookups. The [deep research guide](https://docs.parallel.ai/task-api/examples/task-deep-research) 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](https://docs.parallel.ai/task-api/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:

```bash
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](https://docs.parallel.ai/getting-started/rate-limits) 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](https://docs.parallel.ai/task-api/guides/choose-a-processor) 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](https://docs.parallel.ai/task-api/guides/specify-a-task):

- **`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](https://docs.parallel.ai/task-api/examples/task-deep-research) 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](https://docs.parallel.ai/api-reference/tasks/create-task-run) 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](https://docs.parallel.ai/task-api/guides/access-research-basis), 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](https://parallel.ai/blog/introducing-basis-with-calibrated-confidences) 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](https://docs.parallel.ai/task-api/guides/choose-a-processor) 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](https://docs.parallel.ai/task-api/best-practices) 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](https://docs.parallel.ai/resources/source-policy) 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](https://docs.parallel.ai/resources/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):

```json
"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](https://docs.parallel.ai/monitor-api/monitor-quickstart) 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](https://docs.parallel.ai/monitor-api/monitor-webhooks)). The detected payload carries an `event_group_id`, not the event itself.

Parallel's [follow-up tasks guide](https://docs.parallel.ai/monitor-api/monitor-task) 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:

```bash
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](https://docs.parallel.ai/api-reference/tasks/create-task-run). `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](https://docs.parallel.ai/task-api/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](https://developers.openai.com/api/docs/deprecations) 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](/alternatives/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](https://docs.parallel.ai/getting-started/pricing).

## 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](/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](/vault), and runs filed under the same `project_id` reuse it ([runs docs](/docs/runs)). 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](/citation-verification-api) takes another tool's output and its sources. The full comparison is at [Parallel Task API vs Hyperresearch](/alternatives/parallel-task-api).
