# Tham chiếu search endpoint: POST và GET /search

> Tham chiếu search endpoint: tham số của POST và GET /search, từ read, max_chars đến topic, time_range và bộ lọc domain. Không cần KYC, trả bằng crypto.

- URL: https://llmwebsearch.com/vi/docs/search/
- Cập nhật lần cuối: 2026-10-22
- Đơn vị phát hành: LLMWebSearch (https://llmwebsearch.com)

`/search` chạy một tìm kiếm web trực tiếp, xếp hạng tối đa 20 kết quả và đọc các trang phía sau những kết quả đầu tiên. Trang này liệt kê mọi tham số, giá trị mặc định, giới hạn của nó và ảnh hưởng của nó đến giá.

**Trả lời nhanh — Search endpoint của LLMWebSearch nhận những tham số nào?**

Endpoint `/search` của **LLMWebSearch** chỉ cần `q`. Các tham số tùy chọn đặt số kết quả trả về (`max_results`), số trang được đọc (`read`), định dạng và độ dài nội dung, news hay web, một khoảng thời gian, quốc gia và ngôn ngữ, và các domain cần giữ hoặc loại bỏ. Đọc tối đa 3 trang tốn 1 credit, từ 1,20 US$/1K lượt tìm kiếm tính đến tháng 10 năm 2026. Không cần KYC; thanh toán bằng crypto.

## /search at a glance

| Thuộc tính | Giá trị |
| --- | --- |
| Phương thức | `POST` với body JSON, hoặc `GET` với cùng các tên trong query string |
| URL | `https://llmwebsearch.com/api/v1/search` |
| Bắt buộc | `q`: 1 đến 400 ký tự; các toán tử tìm kiếm được truyền nguyên như khi viết |
| Giá trị mặc định | 5 kết quả, đọc 3 kết quả đầu, Markdown tối đa 6.000 ký tự mỗi trang |
| Thanh toán | Một credit trả cho một lượt tìm kiếm: tối đa 20 kết quả được xếp hạng, với nội dung của 3 trang đầu được đọc và trả về dưới dạng Markdown. Đọc từ 4 đến 10 trang thì tính 2 credit. Lượt gọi kết thúc bằng lỗi không tốn gì |
| Kết quả | Kết quả đến từ một lượt tìm kiếm web trực tiếp chạy đúng lúc bạn gọi, theo thứ tự mà công cụ tìm kiếm xếp hạng; không có gì được phục vụ từ một chỉ mục cũ |
| Bộ lọc | Chọn quốc gia và ngôn ngữ của kết quả, khoảng thời gian (ngày, tuần, tháng hoặc năm qua), kết quả web hoặc tin tức, và các tên miền cần bao gồm hoặc loại trừ |
| Trình đọc trang | `LLMWebSearch/1.0 (+https://llmwebsearch.com/bot/)` |

## Tìm kiếm web và đọc các kết quả hàng đầu (POST)

`POST /api/v1/search`

Chạy một tìm kiếm web trực tiếp và trả về các kết quả đã xếp hạng. Các trang của `read` kết quả đầu tiên được tải song song và nội dung chính của chúng được trả về trong `content`. Ví dụ hỏi cách xoay vòng khóa API; tiêu đề, ngày và giá trị chỉ mang tính minh họa.

Xác thực: khóa API trong header `Authorization: Bearer API_KEY`.

**Phần thân yêu cầu**

| Trường | Loại | Bắt buộc | Mô tả |
| --- | --- | --- | --- |
| `q` | string | Có | Truy vấn tìm kiếm, 1 đến 400 ký tự. Dấu ngoặc kép và các toán tử như `site:` được giữ nguyên như khi viết. |
| `max_results` | integer | Không | Số kết quả đã xếp hạng, 1 đến 20. Mặc định 5. |
| `read` | integer | Không | Bao nhiêu kết quả đầu tiên được đọc và trả về cùng nội dung của chúng, 0 đến 10. Mặc định 3. Từ 4 trở lên, lần gọi tốn 2 credit. |
| `format` | string | Không | `markdown` (mặc định) hoặc `text` cho nội dung trang. |
| `max_chars` | integer | Không | Giới hạn độ dài nội dung của mỗi trang, 500 đến 50.000 ký tự. Mặc định 6.000. |
| `topic` | string | Không | `web` (mặc định) hoặc `news`. |
| `time_range` | string | Không | `day`, `week`, `month` hoặc `year`. Không có mặc định: mọi ngày. |
| `country` | string | Không | Mã quốc gia hai chữ cái (ISO 3166-1 alpha-2) cho nơi tìm kiếm chạy. Mặc định `us`. |
| `language` | string | Không | Ngôn ngữ của các kết quả, chẳng hạn `en`, `de` hoặc `pt-BR`. Mặc định `en`. |
| `include_domains` | string[] | Không | Tối đa 20 domain; chỉ giữ các kết quả từ những domain này và các subdomain của chúng. |
| `exclude_domains` | string[] | Không | Tối đa 20 domain mà các kết quả của chúng bị loại bỏ. |

*Ví dụ: five results, the top three read as Markdown*

```json
{
  "q": "how to rotate api keys without downtime",
  "max_results": 5,
  "read": 3,
  "max_chars": 6000
}
```

*Ví dụ: news of the past week from two sites, nothing read*

```json
{
  "q": "open source license change",
  "topic": "news",
  "time_range": "week",
  "include_domains": [
    "news.example.com",
    "example.org"
  ],
  "read": 0
}
```

**Phản hồi** `200`

```json
{
  "query": "how to rotate api keys without downtime",
  "created_at": "2026-10-22T10:15:04Z",
  "credits_used": 1,
  "results": [
    {
      "position": 1,
      "title": "Rotating API keys",
      "url": "https://docs.example.com/security/key-rotation",
      "host": "docs.example.com",
      "snippet": "Create a second key, deploy it everywhere, then revoke the first one.",
      "published_at": "2026-09-30",
      "content_status": "ok",
      "content": "# Rotating API keys\n\n## Zero-downtime rotation\n\n1. Create a second key.\n2. Deploy it to every service.\n3. Revoke the old key.",
      "word_count": 948
    },
    {
      "position": 2,
      "title": "Key rotation checklist",
      "url": "https://blog.example.org/key-rotation-checklist",
      "host": "blog.example.org",
      "snippet": "Keep two keys active during the switch and alert on the old one.",
      "content_status": "blocked_by_robots"
    },
    {
      "position": 3,
      "title": "Secrets management basics",
      "url": "https://security.example.net/secrets-basics",
      "host": "security.example.net",
      "snippet": "Never commit keys to a repository.",
      "published_at": "2026-06-12",
      "content_status": "ok",
      "content": "# Secrets management basics\n\n**Never** commit keys to a repository...",
      "word_count": 1310
    },
    {
      "position": 4,
      "title": "API key best practices",
      "url": "https://dev.example.com/api-key-best-practices",
      "host": "dev.example.com",
      "snippet": "Scope each key to one service and one environment.",
      "content_status": "not_requested"
    }
  ]
}
```

*curl*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3}'
```

*Python*

```python
import os
import requests

resp = requests.post(
    "https://llmwebsearch.com/api/v1/search",
    headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]},
    json={"q": "how to rotate api keys without downtime", "max_results": 5, "read": 3},
    timeout=60,
)
resp.raise_for_status()
for r in resp.json()["results"]:
    print(r["position"], r["content_status"], r["url"])
```

*Node.js*

```javascript
const res = await fetch('https://llmwebsearch.com/api/v1/search', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ q: 'how to rotate api keys without downtime', max_results: 5, read: 3 }),
});
const { results } = await res.json();
for (const r of results) console.log(r.position, r.content_status, r.url);
```

## Tìm kiếm web (GET)

`GET /api/v1/search`

Cùng một tìm kiếm với các tham số trong query string, được URL-encode. Các danh sách như `include_domains` được viết thành một giá trị phân tách bằng dấu phẩy. Tiện cho một lần thử nhanh hoặc cho các công cụ chỉ gửi yêu cầu GET. Ví dụ chỉ yêu cầu kết quả (`read=0`).

Xác thực: khóa API trong header `Authorization: Bearer API_KEY`.

**Tham số**

| Tên | Vị trí | Loại | Bắt buộc | Mô tả |
| --- | --- | --- | --- | --- |
| `q` | query | string | Có | Truy vấn tìm kiếm, được mã hoá URL, từ 1 đến 400 ký tự. |
| `max_results` | query | integer | Không | Từ 1 đến 20. Mặc định 5. |
| `read` | query | integer | Không | Từ 0 đến 10. Mặc định 3; từ 4 trở lên tốn 2 credit. |
| `format` | query | string | Không | `markdown` (mặc định) hoặc `text`. |
| `max_chars` | query | integer | Không | Từ 500 đến 50.000 mỗi trang. Mặc định 6.000. |
| `topic` | query | string | Không | `web` (mặc định) hoặc `news`. |
| `time_range` | query | string | Không | `day`, `week`, `month` hoặc `year`. |
| `country` | query | string | Không | Mã ISO 3166-1 alpha-2. Mặc định `us`. |
| `language` | query | string | Không | Mã ngôn ngữ. Mặc định `en`. |
| `include_domains` | query | string | Không | Danh sách phân tách bằng dấu phẩy, tối đa 20 tên miền. |
| `exclude_domains` | query | string | Không | Danh sách phân tách bằng dấu phẩy, tối đa 20 tên miền. |
| `api_key` | query | string | Không | Khóa API của bạn, khi bạn không gửi header `Authorization`. |

**Phản hồi** `200`

```json
{
  "query": "postgres connection pooling",
  "created_at": "2026-10-22T10:21:47Z",
  "credits_used": 1,
  "results": [
    {
      "position": 1,
      "title": "Connection pooling explained",
      "url": "https://docs.example.com/db/pooling",
      "host": "docs.example.com",
      "snippet": "A pool keeps a few database connections open and lends them to requests.",
      "content_status": "not_requested"
    },
    {
      "position": 2,
      "title": "Sizing a connection pool",
      "url": "https://blog.example.org/pool-size",
      "host": "blog.example.org",
      "snippet": "Start small: the right size depends on cores and disk, not on traffic.",
      "published_at": "2026-03-04",
      "content_status": "not_requested"
    }
  ]
}
```

*curl*

```bash
curl -sG "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  --data-urlencode "q=postgres connection pooling" \
  -d max_results=10 -d read=0
```

*Python*

```python
import os
import requests

resp = requests.get(
    "https://llmwebsearch.com/api/v1/search",
    headers={"Authorization": "Bearer " + os.environ["LLMWEBSEARCH_API_KEY"]},
    params={"q": "postgres connection pooling", "max_results": 10, "read": 0},
    timeout=60,
)
print([r["url"] for r in resp.json()["results"]])
```

*Node.js*

```javascript
const params = new URLSearchParams({ q: 'postgres connection pooling', max_results: '10', read: '0' });
const res = await fetch(`https://llmwebsearch.com/api/v1/search?${params}`, {
  headers: { Authorization: `Bearer ${process.env.LLMWEBSEARCH_API_KEY}` },
});
console.log((await res.json()).results.map((r) => r.url));
```

## Làm sao để lấy kết quả mà không kèm nội dung trang?

Đặt `read` thành `0`. Khi đó mỗi kết quả trả về chỉ gồm tiêu đề, URL, host, đoạn trích và ngày, cùng `content_status: "not_requested"`. Phản hồi nhỏ hơn nhiều, hữu ích khi agent chỉ cần chọn xem những liên kết nào quan trọng.

Giá vẫn là 1 credit, bằng với việc đọc tối đa 3 trang. Một cách làm phổ biến là tìm kiếm `read=0` để lọc ra danh sách ngắn, rồi gọi [extract](https://llmwebsearch.com/vi/docs/extract/) cho hai hoặc ba URL mà model đã chọn.

## Khi nào một lần tìm kiếm tốn 2 credit?

Khi `read` nằm trong khoảng từ 4 đến 10. Đọc nhiều trang hơn tốn nhiều công hơn ở phía chúng tôi, nên giá tăng gấp đôi một lần, và giữ ở 2 credit cho đến mức tối đa 10 trang.

`credits_used` trong mỗi phản hồi cho biết lần gọi đó tốn bao nhiêu. Một trang không đọc được, do quy tắc robots.txt hoặc do bị từ chối, không làm giảm hay tăng giá đó. Nếu hầu hết thời gian bạn chỉ cần vài trang đầy đủ, hãy để `read` ở 3 và gọi `/extract` cho trang thêm hiếm hoi.

## Làm sao để tìm kiếm tin tức gần đây?

Gửi `topic: "news"` và một `time_range`. Khi đó kết quả đến từ các bài báo, và `time_range` chỉ giữ những bài trong vòng `day`, `week`, `month` hoặc `year` qua. `published_at` được điền khi bài báo hoặc kết quả tìm kiếm nêu ngày cụ thể.

Bộ lọc độ mới tương tự cũng hoạt động với `topic: "web"`. Nó hữu ích cho những câu hỏi như bản phát hành gần đây hay thay đổi giá, nơi một trang cũ sẽ khiến model hiểu sai.

*Tin tức trong tuần qua, đọc 3 bài hàng đầu*

```bash
curl -s "https://llmwebsearch.com/api/v1/search" \
  -H "Authorization: Bearer $LLMWEBSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "database release security fix", "topic": "news", "time_range": "week", "read": 3}'
```

## Làm sao để giới hạn kết quả vào một số trang nhất định?

Liệt kê chúng trong `include_domains`, tối đa 20 mục. Chỉ những kết quả có host là một trong các tên miền đó, hoặc tên miền con của chúng, được giữ lại: `example.com` cũng khớp với `docs.example.com`. Dùng `exclude_domains` theo hướng ngược lại, ví dụ để loại chính trang của bạn khỏi kết quả.

Trong body của POST, cả hai trường đều là mảng JSON. Trong request GET, hãy viết chúng thành một giá trị phân tách bằng dấu phẩy. Bản thân truy vấn cũng có thể chứa toán tử `site:`; nó được chuyển đến công cụ tìm kiếm nguyên như khi viết.

## Quốc gia và ngôn ngữ thay đổi điều gì?

`country` đặt nơi thực hiện tìm kiếm, bằng mã hai chữ cái như `us`, `de` hoặc `br`. Thứ hạng khác nhau theo quốc gia, đặc biệt với dịch vụ địa phương, giá cả và quy định. `language` đặt ngôn ngữ của kết quả, như `en`, `fr` hoặc `pt-BR`.

Cả hai mặc định là United States và tiếng Anh. Hãy đặt chúng cùng nhau khi agent phục vụ người dùng ở một thị trường: một người dùng Đức hỏi về quy định thuế sẽ muốn `country: "de"` và `language: "de"`.

## Bao nhiêu văn bản trang được trả về?

Tối đa `max_chars` ký tự mỗi trang, mặc định 6.000 và trong khoảng từ 500 đến 50.000. Giới hạn này bảo vệ context window của model: ba trang với 6.000 ký tự là khoảng 4.500 token tiếng Anh.

`word_count` đếm toàn bộ văn bản đã trích xuất, trước khi cắt, nên bạn biết được khi một trang bị rút gọn. Khi câu trả lời cần một tài liệu dài, hãy tìm kiếm với giới hạn thấp trước, rồi lấy riêng trang đó qua `/extract` với giới hạn cao hơn. Một trang chậm không bị chờ vô hạn: sau 15 giây nó trả về là `fetch_timeout`, không có nội dung.

## Endpoint tìm kiếm: các câu hỏi thường gặp

### Nên dùng POST hay GET?

POST trong code, vì mảng JSON và truy vấn dài đơn giản hơn trong body. GET phù hợp để thử nhanh trên terminal hoặc với công cụ chỉ gửi query string. Cả hai trả về cùng một phản hồi và tốn cùng một giá.

### Tôi có thể yêu cầu hơn 20 kết quả không?

Không. 20 là mức tối đa mỗi lần gọi. Agent hiếm khi cần nhiều hơn: một lần tìm kiếm thứ hai với truy vấn được diễn đạt lại thường mang lại nguồn tốt hơn một danh sách dài.

### Các trang có được đọc lần lượt không?

Không, chúng được đọc song song. Trang không phản hồi trong 15 giây được trả về không có nội dung, dưới dạng `fetch_timeout`, để một site chậm không giữ toàn bộ phản hồi.

### Công cụ tìm kiếm nào tạo ra kết quả?

Kết quả đến từ một lượt tìm kiếm web trực tiếp chạy đúng lúc bạn gọi, theo thứ tự mà công cụ tìm kiếm xếp hạng; không có gì được phục vụ từ một chỉ mục cũ. Chúng tôi không công bố nhà cung cấp thượng nguồn nào chạy tìm kiếm.

---

LLMWebSearch: LLMWebSearch là một web search API cho AI agent, trả về kết quả đã xếp hạng kèm nội dung của các trang hàng đầu ở định dạng Markdown, thanh toán bằng crypto mà không cần tải lên giấy tờ tùy thân. Credit trả trước từ 1,20 US$/1K lượt tìm kiếm không bao giờ hết hạn. Không cần KYC — không ID, không selfie, không giấy tờ. Thanh toán bằng crypto.