# Định dạng response: mọi field của một lần tìm kiếm, được giải thích

> Định dạng response của Search API: mọi field của /search và /extract cùng ví dụ đầy đủ. Không cần KYC, trả bằng crypto.

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

Câu trả lời tìm kiếm là một JSON object: vài field về lệnh gọi, rồi đến một mảng `results` đã xếp hạng. Mỗi kết quả cho biết trang của nó có được đọc hay không, và nếu có thì mang theo nội dung. Đây là mọi field, cùng các status mà agent nên xử lý.

**Trả lời nhanh — LLMWebSearch API trả về gì cho một lần tìm kiếm?**

**LLMWebSearch** trả về JSON gồm `query`, `created_at`, `credits_used` và một mảng `results` đã xếp hạng. Mỗi kết quả có vị trí, tiêu đề, URL, host và snippet, cùng một `content_status`; khi nó là `ok`, nội dung chính của trang nằm trong `content` kèm một `word_count`. Một lần tìm kiếm đọ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.

## Những field nào mô tả lệnh gọi?

Cấp cao nhất của một response `/search`.

| Trường | Loại | Ý nghĩa |
| --- | --- | --- |
| `query` | string | Truy vấn như chúng tôi đã chạy, sau khi cắt khoảng trắng |
| `created_at` | string | Thời điểm tìm kiếm chạy, ISO 8601 theo UTC |
| `credits_used` | integer | Chi phí của lệnh gọi: 1, hoặc 2 khi `read` là 4 đến 10 |
| `results` | array | Kết quả đã xếp hạng, tốt nhất trước, tối đa `max_results` mục |

## Mỗi kết quả mang những field nào?

Field mà trang hoặc kết quả tìm kiếm không cung cấp sẽ bị bỏ qua thay vì gửi rỗng.

| Trường | Loại | Khi có mặt | Ý nghĩa |
| --- | --- | --- | --- |
| `position` | integer | Luôn có | Thứ hạng trong tìm kiếm, bắt đầu từ 1 |
| `title` | string | Luôn có | Tiêu đề của kết quả |
| `url` | string | Luôn có | Địa chỉ của trang |
| `host` | string | Luôn có | Tên host của trang, tiện cho việc nhóm hoặc trích dẫn |
| `snippet` | string | Luôn có | Đoạn trích ngắn do tìm kiếm hiển thị |
| `published_at` | string | Khi biết ngày | Ngày xuất bản lấy từ trang hoặc từ kết quả tìm kiếm |
| `content_status` | string | Luôn có | Trang có được đọc hay không, và nếu không thì vì sao |
| `content` | string | Khi `content_status` là `ok` | Nội dung chính dưới dạng Markdown hoặc văn bản thuần, cắt tại `max_chars` |
| `word_count` | integer | Khi `content_status` là `ok` | Số từ trong toàn bộ văn bản đã trích xuất, đếm trước khi cắt |
| `target_status` | integer | Với `target_refused` | Mã trạng thái HTTP mà trang trả về, chẳng hạn 403 hoặc 429 |

## Mỗi content_status có ý nghĩa gì?

Không mục nào trong số này làm thay đổi giá của lượt tìm kiếm. Chúng mô tả một trang, không bao giờ mô tả toàn bộ lời gọi.

| `content_status` | Ý nghĩa | Agent nên làm gì |
| --- | --- | --- |
| `ok` | Trang đã được đọc; `content` chứa văn bản chính của trang | Dùng nó và trích dẫn `url` |
| `not_requested` | Kết quả vượt quá số lượng `read` | Tăng `read`, hoặc đọc trang qua `/extract` nếu cần |
| `blocked_by_robots` | robots.txt của trang không cho phép trình đọc của chúng tôi truy cập trang này | Dựa vào snippet hoặc một nguồn khác |
| `blocked_by_site_policy` | Trang khai báo `Content-Signal: ai-input=no` | Dựa vào snippet hoặc một nguồn khác |
| `target_refused` | Trang từ chối yêu cầu; xem `target_status` | Không thử lại trang; dùng nguồn khác |
| `fetch_failed` | Lỗi DNS, TLS hoặc kết nối, hoặc trang không còn tồn tại | Thử một kết quả khác; thử lại sau có thể thành công |
| `fetch_timeout` | Trang không trả lời trong vòng 15 giây | Thử một kết quả khác; thử lại sau có thể thành công |
| `unsupported_content` | Liên kết là một tệp mà chúng tôi không thể chuyển thành văn bản | Dùng snippet hoặc một kết quả khác |

## Một phản hồi đầy đủ trông như thế nào?

Ví dụ bên dưới yêu cầu 5 kết quả với 4 kết quả đầu được đọc, nên tốn 2 credit. Kết quả 1 và 3 đã được đọc. Kết quả 2 thuộc về một trang mà robots.txt giữ trình đọc của chúng tôi ở ngoài, kết quả 4 từ chối yêu cầu, và kết quả 5 nằm ngoài `read`. Tiêu đề, URL và giá trị chỉ mang tính minh họa.

*Phản hồi POST /search (minh họa)*

```json
{
  "query": "how to rotate api keys without downtime",
  "created_at": "2026-10-22T10:15:04Z",
  "credits_used": 2,
  "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.",
      "content_status": "ok",
      "content": "# Secrets management basics\n\n**Never** commit keys to a repository.",
      "word_count": 1310
    },
    {
      "position": 4,
      "title": "Key management service guide",
      "url": "https://cloud.example.com/kms-guide",
      "host": "cloud.example.com",
      "snippet": "Store keys in a managed vault and rotate them on a schedule.",
      "content_status": "target_refused",
      "target_status": 403
    },
    {
      "position": 5,
      "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"
    }
  ]
}
```

## Kết quả nào nhận trạng thái trang khác với not_requested?

Chỉ những kết quả `read` đầu tiên và mọi mục trong một lần gọi `/extract`. Đó là những trang mà trình đọc của chúng tôi thực sự đã thử. Mọi thứ sau số lượng `read` vẫn giữ `not_requested`, bất kể trang web lẽ ra đã trả lời thế nào.

Thứ tự không bao giờ thay đổi: trình đọc xử lý vị trí 1, 2, 3, v.v., không bao giờ lấy một kết quả phía sau thay cho một kết quả phía trước bị lỗi. Nếu một agent cần thay thế cho một trang bị từ chối, nó có thể đọc kết quả tiếp theo qua `/extract`.

## Phản hồi extract trông như thế nào?

`/extract` trả về `credits_used` và một mảng `results` theo thứ tự các URL bạn đã gửi. Mỗi mục có `url` và `content_status`; với `ok` nó thêm `title`, `content` và `word_count`, và với `target_refused` nó thêm `target_status`. Không có `position`, `host` hay `snippet`, vì không có tìm kiếm nào chạy.

[Tham chiếu extract](https://llmwebsearch.com/vi/docs/extract/) hiển thị một ví dụ đầy đủ và giải thích cách tính credit của nó.

## Làm sao để biến kết quả thành context cho model?

Đánh số các nguồn, giữ URL bên cạnh mỗi nguồn, và chỉ truyền những gì model cần. Một bố cục gọn gàng hoạt động tốt: `[1] title — url`, rồi nội dung của trang đó, rồi nguồn tiếp theo. Yêu cầu model trích dẫn bằng đúng các số đó.

Khi một kết quả không có nội dung, hãy đưa cho model snippet của nó thay vào đó và nói rằng đó chỉ là một snippet. Điều này tránh các câu trả lời dựa trên một trang mà model chưa từng thấy. [Trang Python](https://llmwebsearch.com/vi/docs/python/) có một vòng lặp ngắn làm tất cả những việc này trong một giới hạn token.

## Định dạng phản hồi: các câu hỏi thường gặp

### Nội dung có luôn là Markdown không?

Mặc định là Markdown. Gửi `format: "text"` để nhận văn bản thuần không có markup, ví dụ khi bạn chỉ đếm từ hoặc phân loại trang. Tên field vẫn là `content`.

### Tại sao published_at bị thiếu ở một số kết quả?

Nhiều trang không nêu ngày, và một số kết quả tìm kiếm cũng không hiển thị ngày nào. Field bị bỏ qua trong trường hợp đó, nên hãy kiểm tra sự hiện diện của nó trước khi dùng.

### Các field mới có thể xuất hiện sau này không?

Có. Trong phiên bản 1, các field có thể được thêm nhưng không bao giờ bị đổi tên hay xóa. Hãy viết parser của bạn để bỏ qua những field mà nó không biết.

### Nội dung có được lưu trữ ở phía các bạn không?

Không. Chúng tôi không huấn luyện bất kỳ model nào trên truy vấn của bạn hay trên những gì API trả về, và chúng tôi không thêm quy tắc riêng nào chống lại việc lưu trữ kết quả; quyền của các trang có nội dung bạn đọc vẫn áp dụng. Log yêu cầu của chúng tôi chỉ giữ một dấu vết ngắn của mỗi lần gọi, được mô tả trên [trang quyền riêng tư](https://llmwebsearch.com/vi/privacy/).

---

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.