choose-your-parallel-api
Choose the right Parallel API and configuration for cost, latency, and answer quality. Use when adding live web data to an app: current events and prices, a cited answer in a chat, grounding an agent in sources it can read in full, reading a URL or PDF, deep research reports, researching or enriching every row of a list or CRM. Use when picking among Search and Extract, Responses, and Task, or when choosing a search mode, reasoning effort, or Task processor. Also use when an integration is too slow, costs more than expected, or misses answers that are on the web.
parallel-web · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add parallel-web/parallel-agent-skills --skill choose-your-parallel-apiAbout this skill
name: choose-your-parallel-api description: "Choose the right Parallel API and configuration for cost, latency, and answer quality. Use when adding live web data to an app: current events and prices, a cited answer in a chat, grounding an agent in sources it can read in full, reading a URL or PDF, deep research reports, researching or enriching every row of a list or CRM. Use when picking among Search and Extract, Responses, and Task, or when choosing a search mode, reasoning effort, or Task processor. Also use when an integration is too slow, costs more than expected, or misses answers that are on the web."
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
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.
- 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.
- 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.
- 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.
- 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:
- Search with
objectiveplus 1–5search_queries, and an excerpt budget big enough to judge relevance (max_results,max_chars_per_result). - Extract the URLs that survived that judgment, with the same
objectiveso excerpts come back focused on the question. Setadvanced_settings.full_contentwhen the whole page is needed.
Extract is $1 per 1,000 URLs, including pages extr
Read the complete source ↗