Live Sandbox BulkScan Live Gateway

API Test Console

Thử nghiệm trực tiếp các Endpoint của BulkScan Traffic API ngay trên trình duyệt. Dữ liệu được gọi trực tiếp từ production server qua REST API.

🔑 X-API-Key Của Bạn (Tự động lưu vào trình duyệt) Chưa kiểm tra key

GET /api/v1/traffic/credits

Tra cứu số dư credit traffic hiện tại và thông tin tài khoản đối tác.

GET

Live Response Console

Waiting for request...

// Bấm các nút thử nghiệm bên trên để xem dữ liệu phản hồi thời gian thực tại đây...

⚡

BulkScan Traffic API Gateway

A high-performance RESTful API gateway designed for Partners and Third-Party Platforms to automate website traffic intelligence, audience engagement, rankings, and traffic sources at scale.

API Specifications

Production Base URL https://bulkscan.io

Authentication Header X-API-Key: bk_live_...

Rate Limit 1 request / 1 second per key

Credit Deduction 1 credit per resolved domain

Authentication

All requests must include the X-API-Key header. Your API Key is linked directly to your BulkScan Partner account and shares your traffic subscription balance atomically.

curl -X GET "https://bulkscan.io/api/v1/traffic/credits" \
  -H "X-API-Key: bk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

GET

Check Credit Balance

Check remaining traffic credits and rate limit allowance for the authenticated partner.

GET /api/v1/traffic/credits

Request Example

curl -X GET "https://bulkscan.io/api/v1/traffic/credits" \
  -H "X-API-Key: YOUR_API_KEY"

Response (200 OK)

{
  "success": true,
  "partner_email": "partner@company.com",
  "partner_role": "partner",
  "traffic_credit_remaining": 966,
  "rate_limit": "1 request / 1 second"
}

POST

Single Domain Traffic Analysis

Deep synchronous traffic analysis for a single website. Returns instant JSON data and deducts 1 credit.

POST /api/v1/traffic/single

Request Body (JSON)

Supports root domains as well as full URLs with protocol (e.g. https://shopee.vn/) which are automatically sanitized.

curl -X POST "https://bulkscan.io/api/v1/traffic/single" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"domain": "shopee.vn"}'

Response (200 OK)

{
  "success": true,
  "input_url": "shopee.vn",
  "canonical_domain": "shopee.vn",
  "remaining_traffic": 965,
  "traffic": {
    "monthly": {
      "2026-06-01": 126371798,
      "2026-07-01": 129251844,
      "2026-08-01": 131213183
    },
    "engagement": {
      "bounce_rate": 0.254,
      "pages_per_visit": 5.9,
      "total_visits": 131213183,
      "avg_duration": { "seconds": 259, "formatted": "04:19" }
    }
  },
  "traffic_sources": {
    "Direct": 37.21,
    "Search": 19.91,
    "Social": 17.23,
    "Referrals": 5.34,
    "Display Ads": 2.47,
    "Email": 0.61,
    "Gen AI": 0.89,
    "Affiliate": 16.34
  },
  "top_countries": [
    { "country": "VN", "country_name": "Vietnam", "share": 0.967 },
    { "country": "US", "country_name": "United States", "share": 0.0113 }
  ],
  "top_keywords": [
    { "keyword": "shopee", "value": 0.22, "volume": 8307270, "cpc": 0.22 }
  ],
  "ranks": { "global": 239, "country": 5, "category": 1 },
  "ai_traffic": {
    "referral_traffic": 0.0089,
    "total_visits": 1163294,
    "chatbots": [
      { "name": "chatgpt", "value": 87.2 },
      { "name": "gemini.google", "value": 8.8 }
    ]
  }
}

POST

Bulk Traffic Analysis (Async)

Submit a batch of up to 5,000 domains as a direct JSON array. Processed concurrently via background workers.

POST /api/v1/traffic/bulk

Request Example (Direct JSON List)

curl -X POST "https://bulkscan.io/api/v1/traffic/bulk" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    "facebook.com",
    "shopee.com",
    "youtube.com",
    "https://shophangduc.vn/"
  ]'

Response (202 Accepted)

{
  "success": true,
  "job_id": "6ab7774d04f3614117e5f94a",
  "status": "queued",
  "total_domains": 4,
  "estimated_time_seconds": 5,
  "poll_url": "/api/v1/traffic/bulk/6ab7774d04f3614117e5f94a",
  "download_url": "/api/v1/traffic/bulk/6ab7774d04f3614117e5f94a/download"
}

GET

Track Job & Download Results

Poll job progress and preview the first 50 results or download the full comprehensive CSV file.

1. Poll Job Status & Preview Results

curl -X GET "https://bulkscan.io/api/v1/traffic/bulk/{job_id}" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "job_id": "6ab7774d04f3614117e5f94a",
  "status": "done",
  "progress": 100,
  "message": "Completed",
  "total_domains": 4,
  "processed_count": 4,
  "download_url": "/api/v1/traffic/bulk/6ab7774d04f3614117e5f94a/download",
  "preview_data": [
    {
      "Domain": "shophangduc.vn",
      "Traffic in June": "1364",
      "Traffic in July": "1679",
      "Traffic in August": "2534",
      "% Change August vs July": "50.92%",
      "Engagement (Bounce / Pages / Duration)": "Bounce: 45.9% | Pages: 1.5 | Duration: 00:37",
      "Top Countries (% Traffic Share)": "Vietnam: 100%",
      "Traffic Sources (%)": "Direct: 21.87% | Search: 50.42% | Referrals: 7.27% | Social: 9.64%..."
    }
  ]
}

2. Download Full CSV Report

curl -O -J "https://bulkscan.io/api/v1/traffic/bulk/{job_id}/download" \
  -H "X-API-Key: YOUR_API_KEY"

Developer SDK Examples

Ready-to-use code snippets in Python and Node.js.

Python (requests)

import requests
import time

API_KEY = "bk_live_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE_URL = "https://bulkscan.io"
HEADERS = {"X-API-Key": API_KEY}

# 1. Gửi mảng domain cào Bulk
domains = ["facebook.com", "shopee.com", "youtube.com", "https://shophangduc.vn/"]
res = requests.post(f"{BASE_URL}/api/v1/traffic/bulk", json=domains, headers=HEADERS).json()
job_id = res["job_id"]
print("Đã tạo Job ID:", job_id)

# 2. Polling chờ hoàn tất
while True:
    time.sleep(2)
    st = requests.get(f"{BASE_URL}/api/v1/traffic/bulk/{job_id}", headers=HEADERS).json()
    print(f"Tiến độ: {st.get('progress')}% ({st.get('status')})")
    if st.get("status") in ("done", "error"):
        break

# 3. Tải file CSV kết quả
if st.get("status") == "done":
    dl = requests.get(f"{BASE_URL}/api/v1/traffic/bulk/{job_id}/download", headers=HEADERS)
    with open(f"result_{job_id}.csv", "wb") as f:
        f.write(dl.content)
    print("✅ Đã lưu file kết quả:", f"result_{job_id}.csv")

Node.js (JavaScript fetch)

const API_KEY = "bk_live_xxxxxxxxxxxxxxxxxxxxxxxx";
const BASE_URL = "https://bulkscan.io";
const headers = { "X-API-Key": API_KEY, "Content-Type": "application/json" };

async function runBulk() {
  const domains = ["facebook.com", "shopee.com", "youtube.com", "https://shophangduc.vn/"];
  const res = await fetch(`${BASE_URL}/api/v1/traffic/bulk`, {
    method: "POST",
    headers,
    body: JSON.stringify(domains)
  });
  const { job_id } = await res.json();
  console.log("Job ID:", job_id);

  let done = false;
  while (!done) {
    await new Promise(r => setTimeout(r, 2000));
    const check = await fetch(`${BASE_URL}/api/v1/traffic/bulk/${job_id}`, { headers });
    const data = await check.json();
    console.log(`Progress: ${data.progress}% (${data.status})`);
    if (data.status === "done" || data.status === "error") {
      done = true;
      console.log("Top Preview Results:", data.preview_data);
    }
  }
}

runBulk();

HTTP Status & Error Codes

Standard HTTP error response specifications.

HTTP Code	Name	Description
200 OK	Success	Request executed successfully.
202 Accepted	Accepted	Bulk job queued for background processing.
400 Bad Request	Invalid Input	Invalid domain format or batch size exceeds 5,000 domains.
401 Unauthorized	Unauthorized	Missing or invalid X-API-Key header.
402 Payment Required	Out of Credit	Your BulkScan account has 0 traffic credits remaining.
403 Forbidden	Permission Denied	Account is not assigned the "partner" role.
404 Not Found	Not Found	Specified job_id or output file does not exist.
409 Conflict	Process Conflict	Another bulk traffic job is already running on this account.
429 Too Many Requests	Rate Limit Exceeded	Exceeded 1 req/sec limit. Please wait 1 second before retrying.

API Test Console

GET /api/v1/traffic/credits

POST /api/v1/traffic/single

POST /api/v1/traffic/bulk

GET /api/v1/traffic/bulk/{job_id}

BulkScan Traffic API Gateway

API Specifications

Authentication

Check Credit Balance

Request Example

Response (200 OK)

Single Domain Traffic Analysis

Request Body (JSON)

Response (200 OK)

Bulk Traffic Analysis (Async)

Request Example (Direct JSON List)

Response (202 Accepted)

Track Job & Download Results

1. Poll Job Status & Preview Results

2. Download Full CSV Report

Developer SDK Examples

Python (requests)

Node.js (JavaScript fetch)

HTTP Status & Error Codes