Documentation

API リファレンス

クォータ管理、使用追跡、セッション履歴用の REST API エンドポイント

Quick Start

Connect your existing Puppeteer, Playwright, or CDP automation to BotCloud by swapping your WebSocket endpoint to wss://cloud.bots.win. No code rewrites — just one line change.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

認証

すべての API エンドポイントはベアラートークン認証が必要です

# All API endpoints require Bearer token authentication
curl -H "Authorization: Bearer your-user-token-here" \
  https://cloud.bots.win/api/quota

GET /api/quota

ジョブ起動前に残クォータを確認

GET/api/quota

Response: 総クォータ、使用済み、残クォータ、使用済みパーセンテージを返します

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/quota

GET /api/usage

レポートとコスト分析の使用統計を取得

GET/api/usage

Response: 総セッション数、総分数、アクティブセッション数を返します

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/usage

GET /api/history

監査証跡のセッション履歴を取得

GET/api/history

Parameters: オプションの開始・終了クエリパラメーター（ISO 8601 タイムスタンプ）

Response: 期間と切断理由を含むセッションオブジェクトの配列を返します

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/history

POST /api/user-data

永続的ブラウザー状態（Cookie、localStorage など）用の新しいユーザーデータコンテナを作成

POST/api/user-data

Response: 作成されたユーザーデータ ID とタイムスタンプを返します

curl -X POST -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

GET /api/user-data

認証されたユーザーのすべてのユーザーデータコンテナをリスト表示

GET/api/user-data

Response: クォータ情報を含むユーザーデータオブジェクトの配列を返します

curl -H "Authorization: Bearer your-token" https://cloud.bots.win/api/user-data

DELETE /api/user-data/:id

ユーザーデータコンテナを削除し、クォータを解放

DELETE/api/user-data/:id

Response: 成功ステータスを返します

curl -X DELETE -H "Authorization: Bearer your-token" \
  https://cloud.bots.win/api/user-data/udd_abc123xyz789defg

Framework Integration

Puppeteer, PuppeteerSharp, Playwright (Node.js / Python / .NET), raw CDP, Go (chromedp / rod), Java (native WebSocket), and Ruby (Ferrum) all work without code rewrites. Swap wss://cloud.bots.win as your endpoint and pass your token, proxy, and device type as query parameters.

import puppeteer from "puppeteer-core";

const params = new URLSearchParams({
  token: process.env.BOTCLOUD_TOKEN,
  "--proxy-server": process.env.BOTCLOUD_PROXY,
  device_type: "mac",
});

const browser = await puppeteer.connect({
  browserWSEndpoint: `wss://cloud.bots.win?${params.toString()}`,
});

const page = await browser.newPage();
await page.goto("https://example.com");
await page.screenshot({ path: "screenshot.png" });
await browser.close();

請求モデル

サブスクリプションプランには月間ブラウザー時間が含まれます。使い切った後は、追加利用がプランの overage レートで前払い残高から差し引かれます。

接続エラー

これらのエラーは接続セットアップ中に発生します — セッションは作成されないため、/api/history には表示されません。HTTPステータスとレスポンスボディのメッセージを確認して対処してください。

HTTP Status	Cause
400	--proxy-server クエリパラメーターが欠落しているか、形式が正しくありません
401	トークンが欠落しているか無効です
401	サブスクリプションが有効ではありません（未登録、失効、または期間終了）
401	トライアルトークンが期限切れか、クォータを使い切りました
403	アカウント残高が不足 — サブスクリプション時間が残っておらず残高がゼロです
429	トライアルアカウントは同時に1つのアクティブセッションに制限されています

切断理由

セッションが開かれると、最終的に以下のいずれかの理由で終了します — /api/history に記録されます。エラー処理と監査証跡にこれらのコードを使用してください。

Code	Description
socket_close	クライアントが接続を閉じた（例: browser.close() またはプロセス終了）— 最も一般的、正常終了
idle_timeout	クライアントからの活動が長時間なかった — ゲートウェイによりセッションが終了
browser_close_graceful	ブラウザーが自ら閉じた（例: ページ内から window.close() が呼び出された）
trial_exhausted	セッション中にトライアルのトークンクォータが使い切られた
primary_blocked:Insufficient balance	セッション途中でアカウント残高が不足 — ゲートウェイがセッションを閉じた
primary_blocked:Subscription lapsed or expired	セッション途中でサブスクリプションが失効または非アクティブになった
browser_disconnect	ブラウザーがゲートウェイから切断された — 再試行可能
browser_crash	ブラウザープロセスがクラッシュした — 再試行可能
gateway_crash	ゲートウェイが再起動した — セッションが終了しました、再試行可能
socket_error	ネットワークレベルのエラー（TCP reset または異常終了）