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 엔드포인트는 Bearer 토큰 인증이 필요합니다

# 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

지속적인 브라우저 상태(쿠키, 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	계정 잔액 부족 — 남은 구독 시간이 없고 잔액이 0입니다
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 또는 비정상 종료)