web-research-parallel

Parallel - Web Research API

Setup

Read your credentials from ~/.gooseworks/credentials.json:

export GOOSEWORKS_API_KEY=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json'))['api_key'])")
export GOOSEWORKS_API_BASE=$(python3 -c "import json;print(json.load(open('$HOME/.gooseworks/credentials.json')).get('api_base','https://api.gooseworks.ai'))")

If ~/.gooseworks/credentials.json does not exist, tell the user to run: npx gooseworks login

All endpoints use Bearer auth: -H "Authorization: Bearer $GOOSEWORKS_API_KEY"

Web research API that returns OpenAI ChatCompletions-compatible responses.

Capabilities

• Retrieve FindAll Run Status: Retrieve a FindAll run (free)
• FindAll Run Result: Retrieve the FindAll run result at the time of the request (free)
• Cancel FindAll Run: Cancel a FindAll run (free)
• Retrieve Task Run Input: Retrieves the input of a run by run_id (free)
• Retrieve Task Run: Retrieves run status by run_id (free)
• Ingest FindAll Run: Transforms a natural language search objective into a structured FindAll spec
• Retrieve Task Run Result: Retrieves a run result by run_id, blocking until the run is completed (free)
• Create FindAll Run: Starts a FindAll run
• Search: Searches the web
• Chat API: Parallel Chat is a web research API that returns OpenAI ChatCompletions compatible streaming text and JSON
• Extract: Extracts relevant content from specific web URLs
• Create Task Run: Initiates a task run

Usage

Retrieve FindAll Run Status (free)

Retrieve a FindAll run.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/findall/runs/{findall_id}"}'

FindAll Run Result (free)

Retrieve the FindAll run result at the time of the request.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/findall/runs/{findall_id}/result"}'

Cancel FindAll Run (free)

Cancel a FindAll run.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/findall/runs/{findall_id}/cancel"}'

Retrieve Task Run Input (free)

Retrieves the input of a run by run_id.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1/tasks/runs/{run_id}/input"}'

Retrieve Task Run (free)

Retrieves run status by run_id.The run result is available from the /result endpoint.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1/tasks/runs/{run_id}"}'

Ingest FindAll Run

Transforms a natural language search objective into a structured FindAll spec.Note: Access to this endpoint requires the parallel-beta header.The generated specification serves as a suggested starting point and can be furthercustomized by the user.

Parameters:

• objective* (string) - Input model for FindAll ingest.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/findall/ingest","body":{"objective":"Find all AI startups in San Francisco"}}'

Retrieve Task Run Result (free)

Retrieves a run result by run_id, blocking until the run is completed.

Parameters:

• timeout (integer)

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1/tasks/runs/{run_id}/result"}'

Create FindAll Run

Starts a FindAll run.This endpoint immediately returns a FindAll run object with status set to ‘queued’.You can get the run result snapshot using the GET /v1beta/findall/runs//result endpoint.You can track the progress of the run by:Polling the status using the GET /v1beta/findall/runs/ endpoint,Subscribing to real-time updates via the /v1beta/findall/runs//eventsendpoint,Or specifying a webhook with relevant event types during run creation to receivenotifications.

Parameters:

• objective* (string) - Input model for FindAll run.
• entity_type* (string) - Type of the entity for the FindAll run.
• match_conditions* (MatchCondition · object[]) - List of match conditions for the FindAll run.
• generator* (enum<string>) - Generator for the FindAll run. One of base, core, pro, preview.
• match_limit* (integer) - Maximum number of matches to find for this FindAll run. Must be between 5 and 1000 (inclusive).
• exclude_list (ExcludeCandidate · object[] | null) - List of entity names/IDs to exclude from results.
• metadata (Metadata · object) - Metadata for the FindAll run.
• webhook (Webhook · object) - Webhook for the FindAll run.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/findall/runs"}'
  "goal": "Find all AI startups in San Francisco"
}'

Search

Searches the web.To access this endpoint, pass the parallel-beta header with the valuesearch-extract-2025-10-10.

Parameters:

• mode (enum<string> | null) - Request to Search API.
• objective (string | null) - Natural-language description of what the web search is trying to find. May include guidance about preferred sources or freshness. At least one of objective or search_queries must be provided.
• search_queries (string[] | null) - Optional list of traditional keyword search queries to guide the search. May contain search operators. At least one of objective or search_queries must be provided.
• processor (enum<string> | null) - DEPRECATED: use mode instead.
• max_results (integer | null) - Upper bound on the number of results to return. May be limited by the processor. Defaults to 10 if not provided.
• max_chars_per_result (integer | null) - DEPRECATED: Use excerpts.max_chars_per_result instead.
• excerpts (object) - Optional settings to configure excerpt generation.
• source_policy (object) - Optional source policy governing domain and date preferences in search results.
• fetch_policy (object) - Fetch policy: determines when to return cached content from the index (faster) vs fetching live content (fresher). Default is to disable live fetch and return cached content from the index.

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/v1beta/search","body":{"objective":"AI agent frameworks comparison 2024"}}'

Chat API

Parallel Chat is a web research API that returns OpenAI ChatCompletions compatible streaming text and JSON.

Parameters:

• model (string)
• messages (array)
• stream (boolean)
• response_format (object)

curl -s -X POST $GOOSEWORKS_API_BASE/v1/proxy/orthogonal/run \
  -H "Authorization: Bearer $GOOSEWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api":"parallel","path":"/chat/completions"}'
  "model": "parallel",
  "messages": [
    {"role": "user", "content": "What are the latest developments in quantum computing?"}
  ]
}'

Extract

Extracts relevant content from specific web URLs.To access this endpoint, pass the parallel-beta header with the valuesearch-extract-2025-10-10.

Parameters:

• urls* (string[]) - Extract request.
• objective (string) - If provided, focuses