SERP API

Xác thực

Tạo key trong ứng dụng › API (gói có SERP API) và gửi trong header của mọi lệnh gọi:

Authorization: Bearer sv_…

Địa chỉ gốc: https://serpy.datlab.dev. Nội dung gửi và nhận là JSON (UTF-8).

MCP cho AI agent

Cùng key, các lệnh gọi này có sẵn cho Claude Code, Cursor, Codex, Hermes Agent… qua máy chủ MCP https://serpy.datlab.dev/mcp: cách cài trong ứng dụng › MCP, hướng dẫn cho agent ở /mcp.txt. Toàn bộ API dạng OpenAPI 3.1: /v1/openapi.json.

POST /v1/search

Tìm một từ khoá trên Google, ưu tiên lên đầu hàng đợi (như Tra ngay). Với wait, chờ kết quả tới bấy nhiêu giây; xong kịp thì trả về kết quả (200), không thì trả về id (202) để hỏi lại. Mỗi lần tìm tính một lượt.

curl -X POST https://serpy.datlab.dev/v1/search \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"giày chạy bộ","domain":"shop.vn","country":"vn","language":"vi","wait":60}'

POST /v1/searches

Nhiều từ khoá (tới 500) cùng domain, quốc gia, ngôn ngữ và số trang, như ô Tìm nhiều trong ứng dụng: vào cuối hàng đợi thành một lần thêm (batch), hoặc với priority lên đầu. Với wait (tới 120 giây), chờ tới khi xong cả hoặc hết giờ. Lượt tìm được hỏi trước: không đủ thì không thêm từ khoá nào.

curl -X POST https://serpy.datlab.dev/v1/searches \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["giày chạy bộ","giày đá bóng"],"domain":"shop.vn","priority":true,"wait":60}'

GET /v1/search/{id}

Trạng thái của một lần tìm (queued, running, done, failed, cancelled), lúc gửi, lúc bắt đầu tìm, lúc xong (mili giây Unix) và kết quả khi xong.

curl https://serpy.datlab.dev/v1/search/9183 \
  -H "Authorization: Bearer sv_…"

GET /v1/searches

Các lần tìm của bạn: đang chờ và đang tìm trước (theo thứ tự hàng đợi, ahead: số lần tìm phía trước), rồi những lần vừa xong. batch: một lần thêm, theo thứ tự đã nhập, lọc và sắp như một dự án.Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/searches?active=1" \
  -H "Authorization: Bearer sv_…"

POST /v1/searches/cancel

Huỷ những lần tìm còn chờ (lần đang tìm thì tìm xong): một (id), một lần thêm (batch) hoặc tất cả (all). Credit của lần đã huỷ được hoàn lại.

curl -X POST https://serpy.datlab.dev/v1/searches/cancel \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"batch":77}'

POST /v1/searches/promote

Đưa các lần tìm đang chờ lên đầu hàng đợi

curl -X POST https://serpy.datlab.dev/v1/searches/promote \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"batch":77}'

POST /v1/track

Như nút Kiểm tra trong ứng dụng: các từ khoá vào dự án của domain mình (dự án tạo mới nếu chưa có, từ khoá đã có không thêm lại) và được kiểm tra ngay. Không có domain nào thì chỉ tìm các từ khoá, ưu tiên lên đầu hàng đợi.

curl -X POST https://serpy.datlab.dev/v1/track \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"shop.vn","items":[{"keyword":"giày chạy bộ"},{"keyword":"giày đá bóng"}]}'

GET /v1/keywords

Các từ khoá bạn đã tìm, mới nhất trước: vị trí gần nhất, trước đó, tốt nhất, xu hướng 12 lần gần nhất.Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/keywords?query=giày" \
  -H "Authorization: Bearer sv_…"

GET /v1/keywords/{id}

Một từ khoá và lần kiểm tra gần nhất với toàn bộ kết quả

curl https://serpy.datlab.dev/v1/keywords/12 \
  -H "Authorization: Bearer sv_…"

GET /v1/keywords/{id}/history

Các lần kiểm tra của một từ khoá, mới nhất trước: vị trí theo thời gian; full=1 kèm toàn bộ kết quả.Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/keywords/12/history?limit=10" \
  -H "Authorization: Bearer sv_…"

GET /v1/checks

Mọi lần kiểm tra của bạn, mới nhất trước, lọc theo từ khoá, domain, quốc gia, ngôn ngữ, hoặc competitor: chỉ những lần có domain đó trong kết quả.Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/checks?keyword=giày chạy bộ&competitor=rival.vn" \
  -H "Authorization: Bearer sv_…"

GET /v1/checks/{id}

Một lần kiểm tra với toàn bộ kết quả trên Google

curl https://serpy.datlab.dev/v1/checks/341 \
  -H "Authorization: Bearer sv_…"

GET /v1/projects

Các dự án và tóm tắt: số từ khoá trong top 3/10/30, vị trí trung bình, lên/xuống, lần kiểm tra gần nhất, lần kiểm tra đang chạy (run) và lần tự kiểm tra tới (next_run) khi có lịch.Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl https://serpy.datlab.dev/v1/projects \
  -H "Authorization: Bearer sv_…"

POST /v1/projects

Tạo dự án, có thể kèm từ khoá và lịch kiểm tra

curl -X POST https://serpy.datlab.dev/v1/projects \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"domain":"shop.vn","schedule":"daily","hour":8,"keywords":["giày chạy bộ","giày đá bóng"]}'

GET /v1/projects/{id}

Một dự án và từng từ khoá: vị trí, trước đó, tốt nhất, URL, xu hướng; mặc định theo thứ tự đã nhập. counts: mỗi lựa chọn của một bộ lọc cho bao nhiêu từ khoá, trong những từ khoá các bộ lọc khác để lại (all của nhóm: cả nhóm; all ngoài cùng: mọi từ khoá); run là lần kiểm tra đang chạy (đã tìm, còn lại, từ khoá đang tìm, eta).Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/projects/3?top=10&order=rank" \
  -H "Authorization: Bearer sv_…"

PATCH /v1/projects/{id}

Đổi những gì gửi kèm: tên, domain, quốc gia, ngôn ngữ, số trang, lịch tự kiểm tra (schedule, days, hour, minute: theo múi giờ của bạn), báo khi kiểm tra xong (notify_channels: email, telegram, zalo). Lịch đặt lại tính từ lúc này; next_run là lần tự kiểm tra tới (mili giây).

curl -X PATCH https://serpy.datlab.dev/v1/projects/3 \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"schedule":"days","days":[1,4],"hour":8,"minute":0}'

DELETE /v1/projects/{id}

Xoá dự án: các lần tìm đang chờ của nó được để riêng; trong undo mili giây có thể khôi phục (restore), sau đó xoá hẳn (lịch sử từ khoá vẫn giữ).

curl -X DELETE https://serpy.datlab.dev/v1/projects/3 \
  -H "Authorization: Bearer sv_…"

POST /v1/projects/{id}/restore

Khôi phục dự án vừa xoá

curl -X POST https://serpy.datlab.dev/v1/projects/3/restore \
  -H "Authorization: Bearer sv_…"

POST /v1/projects/{id}/keywords

Thêm từ khoá vào dự án (có thể ở quốc gia, ngôn ngữ riêng)

curl -X POST https://serpy.datlab.dev/v1/projects/3/keywords \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["dép quai hậu"]}'

POST /v1/projects/{id}/keywords/remove

Bỏ từ khoá khỏi dự án

curl -X POST https://serpy.datlab.dev/v1/projects/3/keywords/remove \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"keywords":["dép quai hậu"]}'

POST /v1/projects/{id}/check

Mọi từ khoá của dự án vào hàng đợi thành một lần kiểm tra (mỗi từ khoá tốn số trang của dự án, tính bằng credit; không đủ credit thì không bắt đầu). Theo dõi bằng GET /v1/projects/{id} (run); đang có lần kiểm tra thì không bắt đầu lần nữa.

curl -X POST https://serpy.datlab.dev/v1/projects/3/check \
  -H "Authorization: Bearer sv_…"

POST /v1/projects/{id}/recheck

Kiểm tra lại một số từ khoá, hoặc những từ khoá lỗi

curl -X POST https://serpy.datlab.dev/v1/projects/3/recheck \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"failed":true}'

POST /v1/projects/{id}/stop

Dừng ngay lần kiểm tra đang chạy: các từ khoá chưa tìm được để riêng (run.stopped), kết quả đã có vẫn giữ; từ khoá đang tìm dở tìm xong rồi dừng. Lượt chưa tìm không bị tính.

curl -X POST https://serpy.datlab.dev/v1/projects/3/stop \
  -H "Authorization: Bearer sv_…"

POST /v1/projects/{id}/resume

Tiếp tục lần kiểm tra đã dừng: các từ khoá đã dừng chờ tìm lại, trong cùng lần kiểm tra (tính credit lại).

curl -X POST https://serpy.datlab.dev/v1/projects/3/resume \
  -H "Authorization: Bearer sv_…"

GET /v1/projects/{id}/days

Dự án theo từng ngày: top 3/10/30, vị trí trung bình

curl "https://serpy.datlab.dev/v1/projects/3/days?days=30" \
  -H "Authorization: Bearer sv_…"

POST /v1/import

Thân yêu cầu là tệp (CSV UTF-8 hoặc .xlsx, tối đa 2 MB, 2.000 dòng): cột từ khoá và có thể cột domain, theo tên cột hoặc hai cột đầu. Trả về các dòng đọc được để gửi tiếp vào /v1/track; không thay đổi gì.

curl -X POST https://serpy.datlab.dev/v1/import \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: text/csv" \
  --data-binary @keywords.csv

POST /v1/projects/{id}/import

Nhập từ khoá từ tệp CSV, Excel hoặc .txt vào dự án

curl -X POST https://serpy.datlab.dev/v1/projects/3/import \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: text/csv" \
  --data-binary @keywords.txt

GET /v1/projects/{id}/export.{format}

Xuất từ khoá của dự án: CSV, Excel hoặc .txt

curl "https://serpy.datlab.dev/v1/projects/3/export.csv?order=rank" \
  -H "Authorization: Bearer sv_…" \
  -o export.csv

GET /v1/keywords/export.{format}

Xuất mọi từ khoá đã tìm: CSV hoặc Excel

curl https://serpy.datlab.dev/v1/keywords/export.xlsx \
  -H "Authorization: Bearer sv_…" \
  -o export.xlsx

GET /v1/searches/export.{format}

Xuất hàng đợi hoặc một batch: CSV hoặc Excel

curl "https://serpy.datlab.dev/v1/searches/export.csv?batch=77" \
  -H "Authorization: Bearer sv_…" \
  -o export.csv

GET /v1/checks/{id}/export.{format}

Xuất kết quả của một lần kiểm tra: CSV hoặc Excel

curl https://serpy.datlab.dev/v1/checks/341/export.csv \
  -H "Authorization: Bearer sv_…" \
  -o export.csv

GET /v1/usage

Credit dùng được ngay (left): credit của gói tháng này còn lại (allowance, của monthly mỗi tháng, hết hạn cuối tháng) và credit đã nạp (credits, không hết hạn); credit đã dùng tháng này; giá (cost.page: credit mỗi trang kết quả của một từ khoá); giới hạn của gói và CrHerd có đang tìm không. Nạp thêm trong app (Nạp tiền).

curl https://serpy.datlab.dev/v1/usage \
  -H "Authorization: Bearer sv_…"

GET /v1/credits/history

Lịch sử credit, mới nhất trước: nạp tiền và thưởng, mỗi lần kiểm tra một dòng (số lần tìm, credit hoàn của lần tìm lỗi hoặc đã huỷ), credit dùng thử, credit của gói mỗi tháng và lúc hết hạn, điều chỉnh của quản trị. filter: all, topup (nạp), spend (kiểm tra), other (còn lại).Danh sách: limit, offset; trang sau ở header X-Next-Offset.

curl "https://serpy.datlab.dev/v1/credits/history?filter=spend&limit=2" \
  -H "Authorization: Bearer sv_…"

GET /v1/locales

Các cặp quốc gia và ngôn ngữ tìm được. Hiện Serpy hỗ trợ Việt Nam / Tiếng Việt; cặp khác bị từ chối với UNSUPPORTED_LOCALE.

curl https://serpy.datlab.dev/v1/locales \
  -H "Authorization: Bearer sv_…"

GET /v1/notifications

Cài đặt thông báo: email, Telegram, Zalo, ngưỡng đổi hạng

curl https://serpy.datlab.dev/v1/notifications \
  -H "Authorization: Bearer sv_…"

PATCH /v1/notifications

Sửa cài đặt thông báo (chỉ những trường gửi lên). Một email nhận thông báo mới chờ xác nhận qua link gửi tới nó (pending); tới lúc đó thông báo vẫn tới email tài khoản.

curl -X PATCH https://serpy.datlab.dev/v1/notifications \
  -H "Authorization: Bearer sv_…" \
  -H "Content-Type: application/json" \
  -d '{"threshold":5,"weekly":true}'

POST /v1/notifications/test

Gửi thử một thông báo tới các kênh đã bật

curl -X POST https://serpy.datlab.dev/v1/notifications/test \
  -H "Authorization: Bearer sv_…"

POST /v1/notifications/resend

Gửi lại link xác nhận email nhận thông báo

curl -X POST https://serpy.datlab.dev/v1/notifications/resend \
  -H "Authorization: Bearer sv_…"

Lỗi

Lỗi trả về { "error": "…", "code": "…" }: error để đọc, code để máy xử lý.