choose-your-parallel-api

Files (1)

• SKILL.md

SKILL.md (first lines)

# Choose the right Parallel API and configuration

This skill covers four Parallel APIs for adding web data to an app. Search finds pages, Extract reads them,
Responses answers a question, Task fills a schema.

**Search and Extract are one pattern, not two choices.** Search locates the pages
and returns excerpts; Extract returns the full content of the ones worth reading.
Most agent integrations want both.

Choose once, while writing the integration — not on every request. A live
classifier in the request path buys flexibility nobody asked for and charges a
model round-trip for it on every call. Decide here; hard-code the result.

Most disappointing results come from choosing the wrong API or configuration, not
from the underlying quality: the right API at the wrong tier, or the right tier
with the wrong knobs. Choose the API first, tier second, knobs third — in that order.

## Setup

`PARALLEL_API_KEY` is the connection secret, server side.

## Step 1 — Know the available surface

```text
POST /v1/search                          # find pages
POST /v1/extract                         # read pages
POST /v1/responses                       # cited answer, synchronous
POST /v1/tasks/runs                      # create a run
GET  /v1/tasks/runs/{run_id}             # status
GET  /v1/tasks/runs/{run_id}/result      # result
GET  /v1/tasks/runs/{run_id}/input       # echo the input
GET  /v1/tasks/runs/{run_id}/events      # progress stream
```

These are the endpoints covered here, not an exhaustive API list. For entity
discovery, use `parallel-findall`; for recurring monitoring, use `parallel-monitor`.
Task Groups also support batch orchestration. Consult the current API docs for
requirements outside this list before declaring them unsupported.

Search supports `turbo`, `fast`, `basic`, and `advanced`; the recommendations below
focus on `turbo`, `fast`, and `advanced`. For Task processors above `pro`, follow
this skill's explicit-consent guidance in Step 3.

Then establish the rest of the requirements before choosing — ask, or read from the
deployment, and state the answers back:

- **What capabilities are required, and how long can the caller wait?** Check
  source freshness, research depth, and output requirements before choosing by
  latency. A waiting caller may still need an asynchronous Task workflow.
- **Is there a concurrency or budget cap?** A ceiling on in-flight Task runs, or a
  cost-per-row target, changes the answer.
- **How many units of work?** One question may need a different API and configuration
  than fifty thousand rows.

## Step 2 — Choose the API

Choose the appropriate branch, checking capabilities before latency.

1. **Who writes the answer — the caller's agent, or Parallel?** The agent writes it,
   from evidence → Search or Extract. Parallel writes it → Responses or Task.
2. **If the caller writes the answer, do they already have the URLs?** Yes → Extract. No → Search first, then
   Extract the results worth reading in full.
3. **If Parallel writes the answer, what evidence and output are needed?** Live
   fetching during research or fields researched per entity favor Task. For a list,
   use one run per row, optionally orchestrated with Task Groups.
4. **Can Responses meet those requirements within the latency budget?** If so,
   prefer it for a caller waiting on a cited answer. Otherwise use Task with
   asynchronous delivery and progress updates.

| Job | API | Shape |
| --- | --- | --- |
| Pages and excerpts for an agent to reason over | **Search** | sync, 200 ms – 3 s |
| Contents of URLs already in hand, including PDFs and JS-rendered pages | **Extract** | sync, 1 – 20 s |
| Grounding an agent in sources it can read in full — the common case | **Search → Extract** | sync, add the two |
| A cited answer inside the request — chat, or an agent loop | **Responses** | sync, 5 – 60 s |
| Research with a caller waiting, when cached sources meet the need | **Responses** at `high` | sync, 30 – 60 s |
| Deep research in the background; structured fields researched per row | **Task** | async, 10 s – 2 hr |

**Responses and Task differ in research configuration as well as delivery.**
Responses `high` uses a latency-focused engine with cache-only extraction; Task
`pro` can fetch live pages during research. A source that requires a live fetch
therefore makes them non-interchangeable, even if a caller is waiting.

**Deep research needs a capability check.** Start with the evidence, freshness,
depth, and output the job requires. Then choose Responses `high` when its
capabilities fit a synchronous answer, or Task `pro` for an asynchronous research
workflow. Validate on representative inputs rather than assuming equal quality.

### Pairing Search with Extract

Search excerpts are compressed and often enough on their own — read them first and
only extract when they are not. When the agent needs the argument of a page rather
than the gist of it, extract the top results:

1. **Search** with `objective` plus 1–5 `search_queries`, and an excerpt budget big
   enough to judge relevance (`max_results`, `max_chars_per_result`).
2. **Extract** the URLs that survived that judgment, with the same `objective` so
   excerpts come back focused on the question. Set
   `advanced_settings.full_content` when the whole page is needed.

Extract is $1 per 1,000 URLs, including pages extracted after a search, so reading
five results in full adds $0.005 to a $0.001–0.005 search. The pattern is cheap; the
mistake is skipping Search and extracting a guessed URL, or skipping Extract and
asking a model to reason from excerpts that were never meant to carry the argument.

Feed both into the model's context with their URLs attached, so citations survive to
the answer.

## Step 3 — Pick the tier

**Start one tier below where instinct lands, measure on 10–20 real inputs, and
escalate only on observed failures.** Each step up is 2–5× the cost; quality does
not scale with it. Escalating on anticipation — buying depth against a difficulty
that never materializes — is the most expensive configuration mistake there is.

### Search modes

| Mode | Latency | $/1k requests | Use when |
| --- | --- | --- | --- |

From parallel-web/parallel-agent-skills, MIT.

More from parallel-web/parallel-agent-skills