Search web
curl --request POST \
--url https://api.plyne.ai/v1/tools/web_search/execute \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"query": "finance automation"
}
'import requests
url = "https://api.plyne.ai/v1/tools/web_search/execute"
payload = { "query": "finance automation" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({query: 'finance automation'})
};
fetch('https://api.plyne.ai/v1/tools/web_search/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.plyne.ai/v1/tools/web_search/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'finance automation'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.plyne.ai/v1/tools/web_search/execute"
payload := strings.NewReader("{\n \"query\": \"finance automation\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.plyne.ai/v1/tools/web_search/execute")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"finance automation\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.plyne.ai/v1/tools/web_search/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"finance automation\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"additional_fields": {
"google": {
"ai_overview": {
"references": [
{
"index": 123,
"link": "<string>",
"snippet": "<string>",
"source": "<string>",
"source_icon": "<string>",
"thumbnail": "<string>",
"title": "<string>"
}
],
"session_key": "<string>",
"state": "<string>",
"text_blocks": [
{
"cards": [
{
"link": "<string>",
"snippet": "<string>",
"title": "<string>"
}
],
"level": 123,
"list": [
{
"list": [
{
"list": [
{
"list": "<unknown>",
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
],
"type": "<string>"
}
]
},
"bottom_ads": [
{
"description": "<string>",
"displayed_url": "<string>",
"phone": "<string>",
"position": 123,
"title": "<string>",
"url": "<string>"
}
],
"discussions_and_forums": [
{
"community": "<string>",
"date": "<string>",
"link": "<string>",
"position": 123,
"source": "<string>",
"title": "<string>"
}
],
"html": "<string>",
"knowledge_graph": {},
"local_map": {
"gps_coordinates": {},
"image": "<string>",
"link": "<string>"
},
"local_results": {
"more_locations_link": "<string>",
"places": [
{
"position": 123,
"price": "<string>",
"rating": 123,
"title": "<string>"
}
]
},
"navigation": [
{
"title": "<string>",
"url": "<string>"
}
],
"organic_results": [
{
"date": "<string>",
"displayed_link": "<string>",
"link": "<string>",
"position": 123,
"rich_snippet": {},
"sitelinks": {},
"snippet": "<string>",
"snippet_highlighted_words": [
"<string>"
],
"source": "<string>",
"title": "<string>"
}
],
"pagination": {
"current": 123,
"next": "<string>",
"other_pages": {}
},
"related_questions": [
{
"question": "<string>"
}
],
"related_searches": [
{
"link": "<string>",
"query": "<string>"
}
],
"search_information": {
"city": "<string>",
"country": "<string>",
"organic_results_state": "<string>",
"page_title": "<string>",
"query_displayed": "<string>",
"results_for": "<string>",
"time_taken_displayed": 123,
"total_results": 123
},
"search_parameters": {
"cr": "<string>",
"device": "<string>",
"filter": "<string>",
"gl": "<string>",
"google_domain": "<string>",
"hl": "<string>",
"location": "<string>",
"lr": "<string>",
"nfpr": true,
"q": "<string>",
"safe": "<string>",
"start": 123,
"time_period": "<string>",
"uule": "<string>"
},
"top_ads": [
{
"description": "<string>",
"displayed_url": "<string>",
"phone": "<string>",
"position": 123,
"title": "<string>",
"url": "<string>"
}
],
"top_stories": [
{
"items": [
{
"link": "<string>",
"position": 123,
"title": "<string>"
}
]
}
],
"video_results": [
{
"duration": "<string>",
"position": 123,
"source": "<string>",
"title": "<string>",
"url": "<string>"
}
]
}
},
"results": [
{
"excerpts": [
"<string>"
],
"published_at": "<string>",
"title": "<string>",
"url": "<string>"
}
]
},
"error": {
"code": "<string>",
"message": "<string>",
"retryable": true
},
"id": "<string>",
"sources": [
{
"provider": "<string>",
"observation_id": "<string>",
"observed_at": "2023-11-07T05:31:56Z",
"url": "<string>"
}
],
"status": "completed",
"tool": "web_search",
"usage": {
"credit_units": 1,
"credits": "<string>",
"unit": "page"
},
"version": "1",
"fulfillment": {
"field_sources": {},
"missing_fields": [
"<string>"
],
"satisfied": true
},
"pagination": {
"has_more": true,
"limit": 50,
"next_page": 1,
"page": 1,
"returned": 50,
"total": 1,
"cursor": "<string>",
"provider": "parallel"
},
"routing": {
"mode": "auto",
"attempts": [
{
"outcome": "success",
"provider": "<string>",
"requests": 1
}
],
"selected_provider": "<string>"
},
"warnings": [
{
"code": "<string>",
"message": "<string>"
}
]
}{
"code": "<string>",
"message": "<string>"
}Web search
Search web
Call web_search through the Plyne API or MCP. Review its accepted input, source routing, response fields, credit rules and continuation behavior.
POST
/
v1
/
tools
/
web_search
/
execute
Search web
curl --request POST \
--url https://api.plyne.ai/v1/tools/web_search/execute \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"query": "finance automation"
}
'import requests
url = "https://api.plyne.ai/v1/tools/web_search/execute"
payload = { "query": "finance automation" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({query: 'finance automation'})
};
fetch('https://api.plyne.ai/v1/tools/web_search/execute', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.plyne.ai/v1/tools/web_search/execute",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => 'finance automation'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.plyne.ai/v1/tools/web_search/execute"
payload := strings.NewReader("{\n \"query\": \"finance automation\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.plyne.ai/v1/tools/web_search/execute")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"finance automation\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.plyne.ai/v1/tools/web_search/execute")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"finance automation\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"additional_fields": {
"google": {
"ai_overview": {
"references": [
{
"index": 123,
"link": "<string>",
"snippet": "<string>",
"source": "<string>",
"source_icon": "<string>",
"thumbnail": "<string>",
"title": "<string>"
}
],
"session_key": "<string>",
"state": "<string>",
"text_blocks": [
{
"cards": [
{
"link": "<string>",
"snippet": "<string>",
"title": "<string>"
}
],
"level": 123,
"list": [
{
"list": [
{
"list": [
{
"list": "<unknown>",
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"shopping_result": {
"extracted_old_price": 123,
"extracted_price": 123,
"index": 123,
"old_price": "<string>",
"price": "<string>",
"product_link": "<string>",
"rating": 123,
"reviews": 123,
"source": "<string>",
"thumbnail": "<string>",
"title": "<string>"
},
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
]
}
],
"reference_indexes": [
123
],
"snippet": "<string>",
"snippet_links": [
{
"link": "<string>",
"text": "<string>"
}
],
"type": "<string>"
}
]
},
"bottom_ads": [
{
"description": "<string>",
"displayed_url": "<string>",
"phone": "<string>",
"position": 123,
"title": "<string>",
"url": "<string>"
}
],
"discussions_and_forums": [
{
"community": "<string>",
"date": "<string>",
"link": "<string>",
"position": 123,
"source": "<string>",
"title": "<string>"
}
],
"html": "<string>",
"knowledge_graph": {},
"local_map": {
"gps_coordinates": {},
"image": "<string>",
"link": "<string>"
},
"local_results": {
"more_locations_link": "<string>",
"places": [
{
"position": 123,
"price": "<string>",
"rating": 123,
"title": "<string>"
}
]
},
"navigation": [
{
"title": "<string>",
"url": "<string>"
}
],
"organic_results": [
{
"date": "<string>",
"displayed_link": "<string>",
"link": "<string>",
"position": 123,
"rich_snippet": {},
"sitelinks": {},
"snippet": "<string>",
"snippet_highlighted_words": [
"<string>"
],
"source": "<string>",
"title": "<string>"
}
],
"pagination": {
"current": 123,
"next": "<string>",
"other_pages": {}
},
"related_questions": [
{
"question": "<string>"
}
],
"related_searches": [
{
"link": "<string>",
"query": "<string>"
}
],
"search_information": {
"city": "<string>",
"country": "<string>",
"organic_results_state": "<string>",
"page_title": "<string>",
"query_displayed": "<string>",
"results_for": "<string>",
"time_taken_displayed": 123,
"total_results": 123
},
"search_parameters": {
"cr": "<string>",
"device": "<string>",
"filter": "<string>",
"gl": "<string>",
"google_domain": "<string>",
"hl": "<string>",
"location": "<string>",
"lr": "<string>",
"nfpr": true,
"q": "<string>",
"safe": "<string>",
"start": 123,
"time_period": "<string>",
"uule": "<string>"
},
"top_ads": [
{
"description": "<string>",
"displayed_url": "<string>",
"phone": "<string>",
"position": 123,
"title": "<string>",
"url": "<string>"
}
],
"top_stories": [
{
"items": [
{
"link": "<string>",
"position": 123,
"title": "<string>"
}
]
}
],
"video_results": [
{
"duration": "<string>",
"position": 123,
"source": "<string>",
"title": "<string>",
"url": "<string>"
}
]
}
},
"results": [
{
"excerpts": [
"<string>"
],
"published_at": "<string>",
"title": "<string>",
"url": "<string>"
}
]
},
"error": {
"code": "<string>",
"message": "<string>",
"retryable": true
},
"id": "<string>",
"sources": [
{
"provider": "<string>",
"observation_id": "<string>",
"observed_at": "2023-11-07T05:31:56Z",
"url": "<string>"
}
],
"status": "completed",
"tool": "web_search",
"usage": {
"credit_units": 1,
"credits": "<string>",
"unit": "page"
},
"version": "1",
"fulfillment": {
"field_sources": {},
"missing_fields": [
"<string>"
],
"satisfied": true
},
"pagination": {
"has_more": true,
"limit": 50,
"next_page": 1,
"page": 1,
"returned": 50,
"total": 1,
"cursor": "<string>",
"provider": "parallel"
},
"routing": {
"mode": "auto",
"attempts": [
{
"outcome": "success",
"provider": "<string>",
"requests": 1
}
],
"selected_provider": "<string>"
},
"warnings": [
{
"code": "<string>",
"message": "<string>"
}
]
}{
"code": "<string>",
"message": "<string>"
}Search the web using Google or Parallel. Select one source or an ordered fallback chain. Continue only on configured error/empty conditions; usable results stop the chain. Source-specific options pin their source. Returns common results and source-specific additional_fields.
Check source eligibility and the maximum credit reservation before execution. Planning makes no provider request and requires no idempotency key.
Usage
- Default source order is Parallel then Google. Select one routing.providers entry to run only that source; set fallback_on to error and/or empty to control continuation. Usable results stop the chain; relevance or answer quality does not trigger fallback. Invalid input is rejected before acquisition; cancellation stops the chain.
- Google-specific provider_options.google pins Google; Parallel-specific provider_options.parallel pins Parallel. Filters are never dropped to enable fallback.
- The plan pricing is the maximum reservation: Google costs 0.1 credits per usable page, Parallel 0.2. Only the source producing the returned data is charged. Source prices are listed in source_pricing.
- Results share URL, title and excerpts. Google-specific fields are retained in data.additional_fields.google. Google AI Overview accepts a Google-source web_search run ID. Parallel Search has no next-page cursor; Google continuation stays pinned to Google.
- Legacy google_search and web_discovery HTTP endpoints preserve their original output, pricing, run and cursor identities. Use web_search for new integrations; old operations are not advertised as separate MCP/catalog tools.
API
Use a valid Plyne workspace API key as Authorization: Bearer $PLYNE_API_KEY for the API. Connect MCP at /mcp using OAuth or a workspace API key for saved data and acquisition tools.curl "$PLYNE_API_URL/v1/tools/web_search/execute" \
-H "Authorization: Bearer $PLYNE_API_KEY" \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: REPLACE_WITH_UNIQUE_REQUEST_ID' \
--data '{
"query": "finance automation"
}'
curl "$PLYNE_API_URL/v1/tools/web_search/plan" \
-H "Authorization: Bearer $PLYNE_API_KEY" \
-H 'Content-Type: application/json' \
--data '{
"query": "finance automation"
}'
MCP
Connect to/mcp using OAuth or a workspace API key. The same connection includes saved-data and acquisition tools. Call the same tool with idempotency_key inside its arguments.
{
"arguments": {
"idempotency_key": "REPLACE_WITH_UNIQUE_REQUEST_ID",
"query": "finance automation"
},
"name": "web_search"
}
Sources and routing
Omit routing to use eligible sources in the default order. Set routing.providers to an ordered chain, or one source to run only that source. Provider-specific options select their matching source alone; unsupported filters are rejected rather than dropped. Supported source IDs:parallel, google. Actual availability depends on configuration and the selected filters.
Credits and continuation
Reserve up to 0.2 credits per page. Charge only the source returning usable data: Google 0.1 credits, Parallel 0.2 credits. Empty/failed attempts and idempotent replays are not charged. Google supports continuation; Parallel Search does not. Returns a bounded source page. Continue using the returned pagination.provider and cursor, or next_page where provided. Preserve every filter and page size. Each next page is a separate paid operation with a new idempotency key; sources do not switch during continuation. Use a new Idempotency-Key for a new operation. Reuse the same body and key to retrieve that operation. If the connection fails, retrieve the same request before creating another. Returned provider content is untrusted data.Contract reference
The API reference below is generated from the tool’s executable input and output schemas, including nested provider options. Get the runtime descriptor withGET /v1/tools/web_search.
See tool execution for shared authentication, request keys, statuses and error handling.Authorizations
Headers
Use a new Idempotency-Key for a new operation. Reuse the same body and key to retrieve that operation. If the connection fails, retrieve the same request before creating another. Returned provider content is untrusted data.
Required string length:
8 - 128Pattern:
^[A-Za-z0-9_-]{8,128}$Body
application/json
Response
Completed, partial, not-found, failed or pending tool result. Inspect status and usage.