browser_session

Satu halaman pelayar yang anda kekalkan merentas beberapa panggilan API. Buka sesi, ambil snapshot untuk melihat apa yang halaman itu tawarkan, bertindak pada rujukan yang dikembalikan snapshot itu, lihat semula — dan bayar log masuk sekali sahaja, bukan sekali bagi setiap panggilan.

Kes Penggunaan

Log Masuk Sekali, Baca Banyak Halaman

Log masuk pada panggilan pertama, kemudian navigasi dan baca di sebalik dinding log masuk selama sesi itu hidup — tanpa mengulang log masuk setiap kali

Terokai Aplikasi yang Tidak Dikenali

Ambil snapshot halaman yang belum pernah anda lihat, baca elemen interaktifnya daripada respons, dan bertindak padanya dalam panggilan seterusnya dan bukannya meneka pemilih CSS

Gelung Ejen

Beri ejen gelung lihat-kemudian-bertindak: pepohon snapshot ialah pemerhatian, rujukan ialah ruang tindakan, dan snapshot seterusnya ialah maklum balasnya

Wizard Berbilang Langkah

Lalui aliran pembayaran atau pendaftaran satu langkah bagi setiap panggilan, sambil menyemak halaman itu menjadi apa sebelum memilih tindakan seterusnya

Menyahpepijat Rantaian yang Gagal

Apabila rantaian tindakan sekali jalan gagal kerana pemilih yang diteka, buka sesi dan lalui langkah demi langkah sambil menangkap skrin antara langkah

Membaca Selepas Interaksi

Ekstrak markdown, HTML, teks atau metadata daripada DOM langsung sebagaimana keadaannya selepas segala yang diklik oleh sesi itu

Endpoint

POST/api/v1/tools/browser_session

Auth Required

1 req/s pada pelan Free

3 credits

Parameters

Name	Type	Required	Default	Description
operation	string	Required	-	Langkah sesi yang dilakukan oleh panggilan ini: `open`, `snapshot`, `act`, `read`, `screenshot`, `close` atau `list`. Setiap operasi kecuali `open` dan `list` memerlukan `session_id`. Operasi itu juga menetapkan harganya — lihat Operasi dan kosnya di bawah. Example: snapshot
session_id	string	Optional	-	Id yang dikembalikan oleh `operation: "open"`, dibawa pada setiap panggilan seterusnya dalam sesi itu. Diperlukan oleh `snapshot`, `act`, `read`, `screenshot` dan `close`. Id yang tidak dikenali, tamat tempoh, sudah ditutup, atau milik akaun lain semuanya memberi jawapan yang sama, "Session not found" — id tidak boleh dicongak, jadi ralat itu tidak pernah memberitahu anda yang mana satu antara empat keadaan itu. Example: 9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c
url	string	Optional	-	Halaman tempat sesi itu dibuka. Diperlukan oleh `open` dan diabaikan oleh operasi lain — setelah sesi wujud, anda menggerakkannya dengan tindakan `navigate` di dalam `act`. URL itu melalui pengawal SSRF dan robots.txt sasaran sebelum sebarang pelayar dilancarkan, begitu juga setiap navigasi dalam sesi. Example: https://app.example.com/login
stealth	boolean	Optional	false	`open` sahaja. Jalankan sesi dalam enjin senyap Chromium pada profil `medium`, bukan kumpulan pelayar standard. Ia lebih lambat bermula, dan ia memaparkan JavaScript, bukan menyelesaikan cabaran. Sesi mengekalkan tetapan ini sepanjang hayatnya. Example: false
ttl	number	Optional	600	`open` sahaja. Berapa lama sesi itu boleh hidup, dalam saat (30-3600). Sesi ditutup mengikut jam ini tidak kira apa yang sedang anda lakukan, jadi tetapkannya mengikut kerja yang dirancang. Example: 600
activity_ttl	number	Optional	300	`open` sahaja. Berapa lama sesi itu boleh melahu antara panggilan, dalam saat (10-3600). Setiap operasi memulakan semula jam ini; jam yang tamat dahulu akan menutup sesi dan melepaskan halamannya. Example: 300
viewport	object	Optional	-	`open` sahaja. Tetingkap pelayar tempat sesi itu berjalan: `{ width, height }`, lebar 800-1920 dan tinggi 600-1080. Jika ditinggalkan, saiz kumpulan pelayar itu sendiri digunakan. Example: {"width": 1440, "height": 900}
timeout	number	Optional	30000	Bajet masa dalam milisaat untuk kerja pelayar yang dilakukan oleh panggilan ini (10000-120000): navigasi pertama pada `open`, rantaian tindakan pada `act`. Kekalkannya dalam tetingkap REST ~25s. Example: 30000
respect_robots	boolean	Optional	true	Hormati robots.txt tapak sasaran. Jika ditinggalkan, nilai lalai yang patuh (`true`) terpakai: URL yang dilarang untuk `CrawlForge` ditolak sebelum pelayar dibuka dan titik akhir ini tidak mengenakan sebarang caj untuknya, dan setiap tindakan `navigate` di dalam `act` diperiksa dengan cara yang sama. Ia terpakai pada panggilan tempat ia dihantar dan tidak pernah diingati oleh sesi, jadi tindakan mengatasi itu perlu diulang dengan sengaja sebagaimana ia dibuat. Tetapkan kepada `false` hanya untuk sasaran yang anda mempunyai perjanjian sendiri dengannya — tindakan mengatasi itu direkodkan pada API key anda. Example: true
interactive_only	boolean	Optional	true	`snapshot` sahaja. Senaraikan hanya elemen yang menerima penuding atau papan kekunci, iaitu elemen yang mendapat rujukan. Tetapkan kepada false untuk turut menyenaraikan tajuk dan mercu tanda (landmark) — berguna untuk memahami susun atur halaman, tetapi nod itu tidak pernah diberi rujukan. Example: true
max_nodes	number	Optional	200	`snapshot` sahaja. Mengehadkan bilangan nod yang disenaraikan pepohon itu (1-1000) — dengan tetapan lalai `interactive_only`, itu satu rujukan bagi setiap nod. Hasilnya melaporkan `truncated: true` apabila had itu menghentikan pemeriksaan. Example: 200
actions	array	Optional	-	`act` sahaja. 1-20 tindakan pelayar yang dijalankan terhadap halaman yang sudah dipegang oleh sesi itu, dalam perbendaharaan kata yang sama seperti [scrape_with_actions](/docs/api-reference/tools/scrape-with-actions) — `wait`, `click`, `type`, `press`, `scroll`, `screenshot`, `select`, `hover`, `navigate`, `snapshot` — berserta medan khusus mengikut jenis. Halakan `selector` kepada rujukan `@e1` daripada snapshot terakhir sesi itu dan bukannya pemilih CSS yang diteka. `executeJavaScript` ditolak pada API terhos: skrip itu akan berjalan dalam pelayar pada infrastruktur kami, bukan pada mesin anda. Example: [{"type": "type", "selector": "@e1", "text": "user@example.com"}, {"type": "click", "selector": "@e3"}]
continue_on_error	boolean	Optional	false	`act` sahaja. Teruskan menjalankan tindakan yang selebihnya apabila satu gagal, bukannya menghentikan rantaian itu. Hasil bagi setiap tindakan menyatakan yang mana berjalan. Example: false
formats	array	Optional	["markdown"]	`read` sahaja. Apa yang hendak diekstrak daripada halaman sebagaimana keadaannya sekarang: `markdown`, `html`, `text`, `json` (tajuk, metadata dan data berstruktur). Kandungan datang daripada DOM langsung, jadi ia mencerminkan kuki sesi itu dan segala yang telah diklik olehnya — bukan pengambilan semula URL itu. Example: ["markdown", "json"]
full_page	boolean	Optional	false	`screenshot` sahaja. Tangkap keseluruhan halaman boleh tatal, bukan hanya kawasan paparan. Example: false
format	string	Optional	png	`screenshot` sahaja. Format imej: `png` atau `jpeg`. Example: png
quality	number	Optional	80	`screenshot` sahaja. Kualiti JPEG, 0-100. PNG mengabaikannya. Example: 80
selector	string	Optional	-	`screenshot` sahaja. Tangkap satu elemen dan bukan keseluruhan halaman — pemilih CSS, atau rujukan `@e1` daripada snapshot terakhir sesi itu. Example: @e2
max_inline_chars	number	Optional	40000	Untuk `snapshot`, `act` dan `read` sahaja — operasi yang mengembalikan kandungan halaman. Hasil terbesar yang dikembalikan sebaris, dalam aksara JSON-nya (1,000-10,000,000). Melebihinya, respons membawa `preview`, `result_handle`, `total_chars`, `truncated: true` dan `expires_at`, dan [read_result](/docs/api-reference/tools/read-result) membaca selebihnya dengan 1 credit setiap panggilan; medan yang diukur ialah `content.markdown`, `content.text`, `content.html` dan `snapshot.tree`. Hasil tersimpan disimpan selama 1 jam. Sesi itu sendiri tidak terjejas — halaman kekal terbuka dan operasi seterusnya tetap melihatnya sepenuhnya. Example: 40000
redact_pii	boolean \| object	Optional	false	Untuk `snapshot`, `act` dan `read` sahaja; operasi lain mengembalikan maklumat perakaunan dan dibiarkan begitu sahaja. Buang data peribadi daripada teks yang dikembalikan oleh panggilan ini, sebelum hasilnya disimpan atau dihantar balik — halaman yang sudah log masuk, yang `tree` snapshot dan kandungan terekstraknya membawa butiran pemegang akaun, ialah sebab ia wujud. `true` ialah singkatan bagi `{ mode: "fast" }` — keempat-empat kelas regex, bertag. Setiap kali anda meminta penyuntingan, respons membawa `redaction: { entities, count, mode }` di dalam `data`, walaupun tiada apa-apa yang sepadan (`count: 0`), jadi "tiada apa-apa ditemui" tidak pernah disalah anggap sebagai "parameter itu diabaikan". Penyuntingan berjalan sebelum hasil itu disimpan, jadi hasil besar yang dibaca kemudian dengan [read_result](/docs/api-reference/tools/read-result) sudah pun disunting. Dua batas yang disengajakan: alamat (`url`, `link`, `href`, `canonical_url`) tidak pernah disunting, dan kiraan yang diperoleh daripada teks (`content_length`, `word_count`, `character_count`) menggambarkan teks itu sebagaimana ia diekstrak, sebelum penyuntingan. Example: true

Operasi dan kosnya

Setiap panggilan dicaj mengikut operation-nya sendiri, jadi satu lihatan murah tidak membayar harga open yang mahal. Tiada apa-apa berjalan percuma: close dan list masih berkos 1 credit setiap satu.

open — 3 credits

Melancarkan pelayar pada url dan memulangkan sessionId berserta kedua-dua jam tamat tempoh. Operasi paling mahal kerana inilah yang menghidupkan pelayar — lebih banyak kerja daripada satu scrape sekali jalan.

snapshot — 1 credit

Memulangkan pepohon kebolehcapaian halaman itu dengan rujukan stabil pada setiap elemen interaktif — @e1, @e2, … mengikut susunan dokumen. Inilah bahagian "lihat" dalam gelung itu, dan inilah sasaran panggilan seterusnya.

act — 1 credit

Menjalankan sehingga 20 tindakan terhadap halaman yang dipegang sesi itu — satu credit bagi panggilan, bukan bagi setiap tindakan. Sasarkan rujukan yang dipulangkan oleh snapshot terakhir.

read — 2 credits

Mengekstrak DOM langsung dalam format yang anda minta, selepas segala yang diklik oleh sesi itu dan dengan kukinya di tempatnya. Berharga sama seperti scrape, kerana ia pengekstrakan kandungan yang sama.

screenshot — 1 credit

Menangkap halaman, atau satu elemen, sebagaimana keadaannya. Imej itu kembali sebagai URI sumber crawlforge://screenshot/{id} dan bukan base64 sebaris, dan titik akhir REST ini menyalurkan URI itu tanpa menyelesaikannya — jadi buat masa ini bait-baitnya hanya boleh dibaca daripada CrawlForge MCP server.

close — 1 credit

Menamatkan sesi dan memulangkan halaman pelayarnya. Tutup sebaik sahaja anda selesai dan bukannya menunggu TTL tamat — slotnya kecil dan dikongsi.

list — 1 credit

Sesi hidup anda berserta id, URL semasa dan kedua-dua masa tamat tempohnya. Berguna apabila anda kehilangan id, atau ingin tahu sama ada sesi itu masih ada sebelum bertindak padanya.

Berapa lama sesi hidup, dan berapa banyak yang anda dapat

Sesi hidup dalam ingatan bahagian belakang pelaksanaan, pada satu contoh tunggal. Ia tidak terselamat daripada penempatan semula atau pemulaan semula contoh, jadi anggap sessionId sebagai singkat umur dan bersedia untuk panggilan seterusnya menjawab "Session not found" — buka yang baharu dan teruskan. Sesi memang singkat umur secara reka bentuk: ttl (lalai 600s, julat 30-3600) ialah jam mutlak, activity_ttl (lalai 300s, julat 10-3600) ialah jam melahu, dan mana-mana yang tamat dahulu akan menutup sesi itu. Satu API key REST hanya boleh memegang satu sesi pada satu masa. open kedua semasa satu lagi masih hidup ditolak dengan ralat bernama, bukan dibariskan — slot sesi hanya terbuka beberapa minit lagi, jadi menunggu hanya akan menggantung panggilan itu. Bahagian belakang terhos memegang tiga sesi kesemuanya merentas semua pelanggan, dan itulah sebabnya had bagi setiap key ialah satu: close apabila anda selesai dan bukan membiarkan TTL habis, dan pembukaan seterusnya jadi milik anda.

Menyasarkan elemen mengikut rujukan

snapshot meletakkan rujukan stabil pada setiap elemen interaktif yang ditemuinya, dan sesi itu mengekalkan rujukan tersebut selagi ia mengekalkan halamannya — jadi gelungnya ialah buka, snapshot, bertindak pada @e1 / @e2 dalam panggilan yang berasingan, snapshot semula. Itulah maksud sebuah sesi: rantaian sekali jalan terpaksa menamakan pemilihnya sebelum ia melihat halaman itu. Rujukan hanya sah pada dokumen tempat snapshot itu diambil: sebarang navigasi — tindakan navigate, atau klik yang memuatkan halaman baharu — membatalkan semua rujukan, dan bertindak pada rujukan lapuk akan gagal dengan lantang melalui ralat yang meminta anda mengambil snapshot baharu, bukan dengan diam-diam mengklik benda yang salah.

browser_session atau scrape_with_actions?

Kedua-duanya memandu pelayar sebenar dan menerima perbendaharaan kata tindakan yang sama. Bezanya ialah sama ada anda sudah tahu rupa halaman itu.

Guna scrape_with_actions

Rantaian sekali jalan pada halaman yang anda fahami: pemilihnya diketahui, alirannya tetap, dan anda mahu kandungan itu kembali dalam panggilan yang sama. 5 credits, satu perjalanan, dan pelayar ditutup apabila ia pulang.

Guna browser_session

Kerja penerokaan atau berbilang panggilan yang memerlukan anda melihat halaman sebelum bertindak, atau yang memerlukan beberapa panggilan berkongsi satu log masuk. Aliran log masuk-kemudian-baca — open, snapshot, act, act, read, close — berkos 9 credits berbanding 5 bagi rantaian sekali jalan yang jauh lebih mudah gagal kerana pemilih yang diteka.

Log masuk berterusan tiada di sini

Kuki dan localStorage sesi hidup dan mati bersama sesi itu. API ini tiada parameter profil dan tiada cara untuk menyimpan pelayar yang sudah log masuk untuk sesi berikutnya, jadi log masuk perlu dilakukan semula setiap kali anda membuka satu. Profil log masuk tersimpan ialah ciri kemudian yang berpagar untuk kegunaan setempat — jangan rancang aliran kerja terhos berdasarkannya.

Contoh Permintaan

terminalBash

# 1. Open the session (3 credits). The id comes back as data.sessionId.
curl -X POST https://crawlforge.dev/api/v1/tools/browser_session \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "open",
    "url": "https://app.example.com/login",
    "ttl": 600
  }'

# {"success": true, "data": {"sessionId": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c", ...}}

# 2. Look at the page before touching it (1 credit).
curl -X POST https://crawlforge.dev/api/v1/tools/browser_session \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "snapshot",
    "session_id": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c"
  }'

# data.snapshot.tree comes back as:
#   [document] "Sign in"
#     @e1 [textbox] "Email"
#     @e2 [textbox] "Password"
#     @e3 [button] "Sign in"

# 3. Act on those refs in a SEPARATE call (1 credit). Same page, same cookies.
curl -X POST https://crawlforge.dev/api/v1/tools/browser_session \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "act",
    "session_id": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c",
    "actions": [
      {"type": "type", "selector": "@e1", "text": "user@example.com"},
      {"type": "type", "selector": "@e2", "text": "secret123"},
      {"type": "click", "selector": "@e3"},
      {"type": "wait", "duration": 1000}
    ]
  }'

# 4. Read the page the login landed on (2 credits).
curl -X POST https://crawlforge.dev/api/v1/tools/browser_session \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "read",
    "session_id": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c",
    "formats": ["markdown"]
  }'

# 5. Close it rather than waiting for the TTL (1 credit). 8 credits in all.
curl -X POST https://crawlforge.dev/api/v1/tools/browser_session \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "close",
    "session_id": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c"
  }'

Contoh Respons

200 OK180ms

{
  "success": true,
  "data": {
    "success": true,
    "operation": "snapshot",
    "sessionId": "9f2c1e6a-4b7d-4c3e-8a5f-1d2e3f4a5b6c",
    "url": "https://app.example.com/login",
    "stealth": false,
    "expiresAt": 1789459200000,
    "idleExpiresAt": 1789458900000,
    "snapshot": {
      "snapshotId": "a3f19c2d",
      "url": "https://app.example.com/login",
      "title": "Sign in",
      "tree": "[document] \"Sign in\"\n  @e1 [textbox] \"Email\"\n  @e2 [textbox] \"Password\"\n  @e3 [button] \"Sign in\"",
      "refCount": 3,
      "nodeCount": 3,
      "truncated": false,
      "interactiveOnly": true
    }
  },
  "credits_used": 1,
  "credits_remaining": 996,
  "processing_time": 180
}

Field Descriptions

data.operationOperasi yang dilakukan oleh panggilan ini — setiap respons mengulanginya

data.sessionIdHantar ini pada setiap panggilan seterusnya dalam sesi itu

data.urlDi mana halaman sesi itu berada sekarang, yang diubah oleh navigasi

data.expiresAtBila jam mutlak `ttl` tamat, dalam milisaat sejak epok

data.idleExpiresAtBila jam melahu `activity_ttl` tamat; setiap operasi menolaknya ke hadapan

data.snapshot.treePepohon kebolehcapaian. Setiap elemen interaktif membawa rujukan yang anda sasarkan dalam panggilan seterusnya

data.snapshot.refCountBerapa banyak elemen yang mendapat rujukan dalam snapshot ini

data.snapshot.truncatedBenar apabila `max_nodes` menghentikan pemeriksaan sebelum penghujung halaman

credits_usedCredits ditolak untuk panggilan ini — 1 bagi snapshot, 3 bagi open

processing_timeMasa dalam ms bagi panggilan ini sahaja, bukan bagi sesi itu

Pengendalian Ralat

Sesi tidak ditemui (502 TOOL_ERROR)

session_id itu tidak dikenali, tamat tempoh, sudah ditutup, atau milik akaun lain — keempat-empatnya menjawab serupa, jadi id tidak boleh dikuis dari luar. Sesi juga tidak terselamat daripada pemulaan semula bahagian belakang pelaksanaan. Buka yang baharu dan teruskan; panggilan yang gagal tidak dicaj.

Had sesi dicapai (502 TOOL_ERROR)

Anda sudah memegang had maksimum satu sesi terbuka. Panggilan itu ditolak dan bukan dibariskan, kerana slot sesi hanya terbuka mengikut TTL beberapa minit lagi. Hantar operation: "close" untuk sesi yang anda ada — operation: "list" memberitahu anda idnya — atau tunggu TTL-nya.

Runtime pelayar tidak dikonfigurasikan (503 TOOL_NOT_AVAILABLE)

Alat ini memerlukan runtime automasi pelayar. Apabila bahagian belakang pelaksanaan terhos tidak dikonfigurasikan, panggilan memulangkan 503 serta-merta dan tiada credits dicaj.

Bahagian belakang pelaksanaan tamat masa (504 MCP_UPSTREAM_TIMEOUT)

Navigasi atau rantaian tindakan melebihi bajet masa bahagian belakang pelaksanaan. Pendekkan tempoh menunggu, pecahkan rantaian itu kepada dua panggilan act — sesi itu masih ada — atau cuba semula. Kegagalan tidak dicaj.

Disekat oleh robots.txt (502 TOOL_ERROR)

robots.txt sasaran melarang URL ini untuk CrawlForge, jadi tiada pelayar dilancarkan dan tiada apa-apa dicaj. Setiap tindakan navigate di dalam act diperiksa dengan cara yang sama, bukan hanya URL yang anda gunakan untuk membuka. Tetapkan respect_robots: false untuk mengatasinya jika anda mempunyai perjanjian sendiri dengan sasaran — tindakan mengatasi itu direkodkan pada API key anda.

Permintaan tidak sah (400 Bad Request)

Operasi itu kekurangan parameter yang diperlukannya — open tanpa url, act tanpa actions, atau mana-mana operasi selain open dan list tanpa session_id — atau satu tindakan gagal skemanya sendiri. Tiada apa-apa dicaj.

Credits Tidak Mencukupi (402 Payment Required)

Akaun anda tidak mempunyai credits yang mencukupi untuk operasi ini (sehingga 3). Beli lebih banyak credits atau naik taraf pelan anda.

Had Kadar Melebihi (429 Too Many Requests)

Anda telah melebihi had kadar pelan anda. Tunggu sebentar atau naik taraf pelan anda untuk had lebih tinggi.

Petua Pro:

Ambil snapshot selepas apa-apa yang mengubah halaman, bukan hanya pada permulaan — klik yang menavigasi membatalkan semua rujukan, dan pepohon baharu itu berkos 1 credit. Apabila sesi hanya akan menjalankan satu rantaian tetap, scrape_with_actions lebih murah dan hanya satu perjalanan.

Kos Credit

3 credits

1-3 credits setiap operasi

browser_session dicaj mengikut operation, bukan mengikut alat: open 3, read 2, dan snapshot, act, screenshot, close serta list 1 setiap satu. 3 credits ialah silingnya — kos open, dan juga kos yang dicaj bagi operasi yang tidak dikenali. Aliran log masuk-kemudian-baca (open, snapshot, act, act, read, close) berjumlah 9 credits.

Pelan Free: 1,000 credits percubaan sekali sahaja = kira-kira 110 sesi log masuk-kemudian-baca

Pelan Hobby: 5,000 credits/bulan = kira-kira 550 sesi ($19/mo)

Pelan Professional: 50,000 credits/bulan = kira-kira 5,500 sesi ($99/mo)

Pelan Business: 250,000 credits/bulan = kira-kira 27,000 sesi ($399/mo)

Alat Berkaitan

scrape_with_actions

Rantaian tindakan sekali jalan pada halaman yang anda sudah fahami (5 credits)

stealth_mode

Pemaparan anti-pengesanan untuk tapak yang menyekat pelayar biasa (5 credits)

scrape

Baca satu halaman tanpa sebarang interaksi (2 credits)

Bersedia untuk mencuba browser_session? Daftar percuma dan dapatkan 1,000 credits untuk mula membina.