Web Search Basic
Run a web search via the /v1/tools/search endpoint and get structured search results.
POST
/
v1
/
tools
/
search
Web Search Basic
curl --request POST \
--url https://api.moonshot.ai/v1/tools/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text_query": "<string>"
}
'import requests
url = "https://api.moonshot.ai/v1/tools/search"
payload = { "text_query": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({text_query: '<string>'})
};
fetch('https://api.moonshot.ai/v1/tools/search', 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.moonshot.ai/v1/tools/search",
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([
'text_query' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.moonshot.ai/v1/tools/search"
payload := strings.NewReader("{\n \"text_query\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.moonshot.ai/v1/tools/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text_query\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.ai/v1/tools/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text_query\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"search_results": [
{
"authority": "<string>",
"date": "<string>",
"icon": "<string>",
"mime": "<string>",
"site_name": "<string>",
"snippet": "<string>",
"text": "<string>",
"title": "<string>",
"url": "<string>"
}
]
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}Run a web search and get a list of structured results with title, snippet, site, and URL. Ideal for agent applications that orchestrate their own search logic.
The string fields above are returned as empty strings when no data is available.Response ExampleCommon Response Headers
All responses, including error responses, carry these two headers.
Usage Example
Usage Example
import os
import requests
api_key = os.environ.get("MOONSHOT_API_KEY")
url = "https://api.moonshot.ai/v1/tools/search"
response = requests.post(
url,
headers={"Authorization": f"Bearer {api_key}"},
json={
"text_query": "Kimi K2 model release",
"limit": 5,
"timeout_seconds": 10,
},
)
print(response.json())
curl https://api.moonshot.ai/v1/tools/search \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $MOONSHOT_API_KEY" \
-d '{"text_query": "Kimi K2 model release", "limit": 5, "timeout_seconds": 10}'
const apiKey = process.env.MOONSHOT_API_KEY;
async function main() {
const response = await fetch("https://api.moonshot.ai/v1/tools/search", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${apiKey}`,
},
body: JSON.stringify({
text_query: "Kimi K2 model release",
limit: 5,
timeout_seconds: 10,
}),
});
const data = await response.json();
console.log(data);
}
main();
Response Fields
Response Fields
| Field | Type | Description |
|---|---|---|
search_results | array[object] | List of search results; an empty array when nothing matches |
search_results[].authority | string | Authority level of the source |
search_results[].date | string | Date of the search result |
search_results[].icon | string | Site icon URL |
search_results[].mime | string | MIME type of the content |
search_results[].site_name | string | Site name |
search_results[].snippet | string | Snippet of the search result |
search_results[].text | string | Full page content; returned when include_content=true, otherwise an empty string |
search_results[].title | string | Title of the search result |
search_results[].url | string | URL of the search result |
{
"search_results": [
{
"authority": "S",
"date": "2026-06-01",
"icon": "https://platform.kimi.ai/favicon.ico",
"mime": "text/html",
"site_name": "Kimi API Open Platform",
"snippet": "Documentation entry of the Kimi API open platform.",
"text": "",
"title": "API Overview - Kimi API Open Platform",
"url": "https://platform.kimi.ai/docs/api/overview"
}
]
}
| Header | Description |
|---|---|
X-Msh-Track-Id | Request ID. If the client sends this header, its value is reused; otherwise the server generates one. Provide this ID when troubleshooting |
X-Msh-Chat-Id | Session ID, always toolgw-{X-Msh-Track-Id}; provide both IDs when troubleshooting |
Error Codes
Error Codes
| HTTP Status | error.type | Typical message | Description |
|---|---|---|---|
| 400 | invalid_request | invalid request body | The request body is not valid JSON |
| 400 | invalid_request | text_query is required | Missing search query text |
| 400 | invalid_request | timeout_seconds must be less than or equal to 60 | timeout_seconds must be between 1 and 60 |
| 400 | invalid_request | limit must be between 1 and 20 | limit must be between 1 and 20 |
| 401 | - | No error body | Missing or invalid API key |
| 403 | - | No error body | Account inactive or suspended |
| 408 | client_canceled | client canceled the request | The client disconnected before the server responded |
| 429 | rate_limited | project qps limit exceeded | Rate or concurrency limit exceeded; the response carries X-RateLimit-Limit and X-RateLimit-Remaining headers, plus X-RateLimit-Reset when a per-second limit is hit |
| 429 | rate_limit_unavailable | rate limit store unavailable | Rate-limit service temporarily unavailable; retry later |
| 500 | internal_error | Raw internal error text | Internal server error; retry later, and contact support with the X-Msh-Track-Id if it persists |
| 502 | upstream_failed | upstream service failed | Service temporarily unavailable; retry later |
| 504 | timeout | request timeout | The search timed out; increase timeout_seconds or simplify the query and retry |
Billing: you are charged once per successful call (HTTP 200) that returns a non-empty
search_results array; failed or empty-result calls are free. For pricing details, see WebSearch Pricing.Authorizations
The Authorization header expects a Bearer token. Use an MOONSHOT_API_KEY as the token. This is a server-side secret key. Generate one on the API keys page in your dashboard.
Body
application/json
Search query text. Must not be empty.
Search timeout in seconds, from 1 to 60. If omitted, no per-request timeout is applied.
Required range:
1 <= x <= 60Maximum number of results to return, from 1 to 20. Defaults to 5.
Required range:
1 <= x <= 20Whether to return full page content in each result's text field. Defaults to false.
Response
Search results
List of search results; an empty array when nothing matches.
Show child attributes
Show child attributes
Was this page helpful?
⌘I
Web Search Basic
curl --request POST \
--url https://api.moonshot.ai/v1/tools/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"text_query": "<string>"
}
'import requests
url = "https://api.moonshot.ai/v1/tools/search"
payload = { "text_query": "<string>" }
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({text_query: '<string>'})
};
fetch('https://api.moonshot.ai/v1/tools/search', 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.moonshot.ai/v1/tools/search",
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([
'text_query' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$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.moonshot.ai/v1/tools/search"
payload := strings.NewReader("{\n \"text_query\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
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.moonshot.ai/v1/tools/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"text_query\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.moonshot.ai/v1/tools/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"text_query\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"search_results": [
{
"authority": "<string>",
"date": "<string>",
"icon": "<string>",
"mime": "<string>",
"site_name": "<string>",
"snippet": "<string>",
"text": "<string>",
"title": "<string>",
"url": "<string>"
}
]
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}{
"error": {
"message": "<string>",
"type": "<string>",
"code": "<string>"
}
}