crawl_deep

Susuri sesebuah laman keluar dari satu URL permulaan, melebar dahulu, mengikut pautan sehingga mencapai had halaman atau kedalaman anda. Memulangkan setiap halaman yang dicapai berserta tajuknya, kedalamannya dari titik mula, dan berapa banyak pautan yang ditemui di situ.

Kes Penggunaan

Petakan laman dokumentasi

Mulakan di akar dokumentasi dan temui setiap halaman yang boleh dicapai, dengan kedalaman menunjukkan bagaimana maklumat itu bersarang.

Bina senarai URL sebelum mengikis secara berkelompok

Rangkak untuk menemui URL, kemudian hantarkannya kepada batch_scrape untuk mengekstrak kandungan — lebih murah daripada merangkak dengan pengekstrakan penuh.

Audit pautan dalaman

Bilangan pautan setiap halaman dan taburan kedalaman menunjukkan bahagian mana yang kaya dengan pautan dan mana yang hampir yatim.

Semak sedalam mana kandungan anda sebenarnya berada

pages_per_depth mendedahkan sama ada halaman penting berada tiga atau empat klik dari titik masuk.

Endpoint

POST/api/v1/tools/crawl_deep

Auth Required

1 permintaan/s pada pelan Free

4 credits

Parameters

Parameter URL permulaan dinamakan start_url, bukan url. Semua parameter menggunakan snake_case — kunci yang tidak dikenali dibuang secara senyap dan bukannya ditolak, jadi kunci camelCase seperti maxDepth akan diabaikan dan nilai lalai digunakan sebaliknya.

Name	Type	Required	Default	Description
start_url	string	Required	-	URL tempat perangkakan bermula. Wajib. Example: https://example.com/docs
max_pages	number	Optional	10	Bilangan maksimum halaman untuk dilawati, 1-100. Perangkakan berhenti sebaik sahaja jumlah ini dilawati, jadi ia turut mengehadkan kos dan tempoh. Example: 25
max_depth	number	Optional	3	Kedalaman pautan maksimum dari `start_url`, 1-5. Halaman permulaan ialah kedalaman 0. Example: 2
same_domain_only	boolean	Optional	true	Apabila true, hanya pautan yang nama hosnya sepadan dengan `start_url` diikuti. Pautan luaran masih dikira dalam jumlah pautan, tetapi tidak pernah dilawati. Example: true
respect_robots_txt	boolean	Optional	true	Apabila true, robots.txt bagi setiap asal diambil sekali bagi setiap perangkakan dan mana-mana URL yang dilarangnya untuk `CrawlForge` akan dilangkau. robots.txt yang tiada atau tidak dapat dicapai dianggap tiada sekatan. Alias lama bagi `respect_robots`; kedua-dua nama menetapkan perkara yang sama. Example: true
respect_robots	boolean	Optional	true	Hormati robots.txt bagi setiap asal. Ini ialah nama kanonik, dikongsi dengan pelayan MCP CrawlForge; `respect_robots_txt` ialah alias lama dan masih berfungsi — tetapkan mana-mana satu. Dibiarkan pada `true`, `start_url` yang dilarang ditolak dengan 403 sebelum apa-apa diambil dan halaman yang dilarang dilangkau semasa perangkakan. Tetapkan kepada `false` hanya untuk laman yang anda mempunyai perjanjian sendiri dengannya — respons kemudiannya membawa entri `warnings` dan tindakan mengatasi itu direkodkan pada API key anda. Example: true
crawl_delay	number	Optional	1000	Milisaat menunggu antara pengambilan halaman, 0-5000. Dikenakan bermula dari halaman kedua. Tingkatkan nilainya untuk laman kecil atau yang berhad kadar. Example: 1000
timeout	number	Optional	30000	Jumlah bajet perangkakan dalam milisaat, 1000-60000, dibahagi sama rata merentas `max_pages` untuk memberi setiap pengambilan had masanya sendiri. Oleh itu menaikkan `max_pages` memendekkan masa yang dibenarkan bagi mana-mana halaman tunggal. Example: 30000
max_inline_chars	number	Optional	40000	Hasil terbesar yang dikembalikan sebaris, dalam aksara JSON-nya (1,000-10,000,000). Melebihinya, respons membawa `preview` (`max_inline_chars` aksara pertama JSON yang diformat), `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. Hasil tersimpan disimpan selama 1 jam. Example: 40000
redact_pii	boolean \| object	Optional	false	Buang data peribadi daripada teks yang dikembalikan oleh panggilan ini, sebelum hasilnya disimpan atau dihantar balik. Terpakai pada setiap halaman yang dikembalikan oleh rangkak itu. `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"; kelas tanpa padanan ditinggalkan dan bukan dilaporkan sebagai `0`. 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

Permintaan mengenal pasti dirinya dengan token produk CrawlForge, dan robots.txt dipatuhi secara lalai. Peraturan bagi setiap asal diambil sekali bagi setiap perangkakan dan dicache. URL yang dilarang dilangkau tanpa membelanjakan bajet max_pages anda, dan start_url yang dilarang memulangkan 403 sebelum apa-apa diambil — jadi perangkakan yang disekat tidak menelan kos credits.

Bagaimana perangkakan berkelakuan

Elok diketahui sebelum anda membaca angka yang dipulangkannya.

Melebar dahulu, bukan mendalam dahulu

Setiap halaman pada kedalaman 1 dilawati sebelum mana-mana halaman pada kedalaman 2. Dengan max_pages yang rendah anda memperoleh peta yang luas dan cetek, bukan satu cabang yang dalam.

Halaman yang gagal disenaraikan dalam errors

Jika sesebuah halaman tamat masa, tidak dapat dicapai atau menjawab dengan ralat HTTP, ia ditinggalkan daripada pages, disenaraikan dalam errors bersama URL, kedalaman dan sebabnya, dan perangkakan diteruskan. Setiap satu masih menggunakan satu halaman daripada bajet max_pages, jadi pages_attempted ialah pages_crawled campur error_count.

links ialah kiraan, bukan senarai

Setiap entri dalam pages melaporkan berapa banyak pautan boleh ikut yang ditemui di situ. Gunakan extract_links pada halaman tertentu jika anda perlukan URL itu sendiri.

JavaScript tidak dilaksanakan

Halaman diambil melalui HTTP dan dihurai sebagai HTML mentah, jadi pautan yang dipapar di sebelah pelanggan tidak kelihatan dan halamannya tidak pernah ditemui.

Contoh Permintaan

terminalBash

# The starting URL parameter is start_url, not url.
curl -X POST https://crawlforge.dev/api/v1/tools/crawl_deep \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_url": "https://example.com/docs",
    "max_pages": 25,
    "max_depth": 2,
    "same_domain_only": true,
    "crawl_delay": 1000,
    "timeout": 30000
  }'

Contoh Respons

200 OK8,420ms

{
  "success": true,
  "data": {
    "start_url": "https://example.com/docs",
    "pages_attempted": 13,
    "pages_crawled": 12,
    "error_count": 1,
    "max_depth_reached": 2,
    "total_links_found": 184,
    "pages": [
      {
        "url": "https://example.com/docs",
        "depth": 0,
        "title": "Documentation",
        "links": 24
      },
      {
        "url": "https://example.com/docs/quickstart",
        "depth": 1,
        "title": "Quickstart",
        "links": 18
      },
      {
        "url": "https://example.com/docs/api",
        "depth": 1,
        "title": "API Reference",
        "links": 31
      }
    ],
    "errors": [
      {
        "url": "https://example.com/docs/legacy",
        "depth": 2,
        "error": "HTTP 404"
      }
    ],
    "crawl_stats": {
      "completed": true,
      "duration_ms": 8380,
      "pages_per_depth": {
        "0": 1,
        "1": 6,
        "2": 5
      }
    }
  },
  "credits_used": 4,
  "credits_remaining": 996,
  "processing_time": 8420
}

Field Descriptions

data.pages_attemptedURL yang diminta oleh perangkakan: pages_crawled campur error_count.

data.pages_crawledHalaman yang diambil dan dihurai, satu entri setiap satu dalam pages. Lebih rendah daripada max_pages apabila ada halaman yang gagal atau laman kehabisan pautan yang boleh dicapai.

data.error_countURL yang diminta tetapi tidak menghasilkan halaman, satu entri setiap satu dalam errors.

data.errorsSatu entri bagi setiap URL yang gagal: url, depth, error (sebabnya, seperti "HTTP 404") dan code apabila diketahui, seperti FETCH_TIMEOUT atau FETCH_FAILED.

data.max_depth_reachedAras terdalam yang dicapai. Lebih rendah daripada max_depth bermakna perangkakan menghabiskan laman itu atau mencapai max_pages dahulu.

data.total_links_foundJumlah kiraan pautan setiap halaman. Ia mengira pendua merentas halaman, jadi ia bukan kiraan URL yang berbeza.

data.pagesSatu entri bagi setiap halaman yang dilawati, mengikut urutan lawatan — melebar dahulu, jadi kedalaman 0 dahulu, kemudian seluruh kedalaman 1.

data.pages.linksBilangan pautan boleh ikut yang ditemui pada halaman itu, bukan URLnya. Gunakan extract_links untuk senarai tersebut.

data.crawl_stats.duration_msMasa yang dihabiskan merangkak, dalam milisaat. Sedikit lebih rendah daripada processing_time pada sampul, yang turut merangkumi pengendalian permintaan.

data.crawl_stats.pages_per_depthBerapa banyak halaman dilawati pada setiap kedalaman — bentuk laman itu sebagaimana dicapai dari start_url.

processing_timeJumlah masa sebenar bagi perangkakan, dalam milisaat.

Pengendalian Ralat

start_url tiada atau tidak sah (400 VALIDATION_ERROR)

Punca paling lazim ialah menghantar url dan bukannya start_url. Kunci yang tidak dikenali dibuang, jadi permintaan itu tiba tanpa sebarang URL permulaan langsung. Tatasusunan details menamakan medan yang gagal.

Parameter di luar julat (400 VALIDATION_ERROR)

max_pages mesti 1-100, max_depth 1-5, crawl_delay 0-5000, timeout 1000-60000. Nilai di luar had itu ditolak dan bukannya dikepit.

start_url dilarang oleh robots.txt (403 ROBOTS_DISALLOWED)

robots.txt sasaran melarang CrawlForge bagi URL tersebut. Tiada apa-apa diambil dan tiada credits dicaj. Tetapkan respect_robots: false — atau alias lamanya respect_robots_txt — hanya apabila anda mempunyai perjanjian sendiri dengan laman itu; tindakan mengatasi itu direkodkan pada API key anda. Tindakan mengatasi itu tidak sampai kepada hos yang berada dalam senarai penarikan diri kekal CrawlForge, yang ditolak tanpa mengira nilai respect_robots.

Perangkakan gagal (500 TOOL_ERROR)

Kegagalan tidak dijangka semasa perangkakan. Kegagalan halaman individu tidak menyebabkan ini — ia disenaraikan dalam errors — jadi 500 bermakna perangkakan itu sendiri tidak dapat diteruskan.

Mengawal kos dan tempoh:

max_pages ialah tuas yang penting. Ia mengehadkan kerja secara langsung, dan kerana timeout dibahagikan merentasnya, max_pages yang tinggi dengan timeout yang rendah memberi setiap halaman masa yang amat singkat dan diam-diam meningkatkan bilangan yang gagal.

Kos credits

4 credits

4 credits setiap permintaan

Rata 4 credits setiap panggilan tanpa mengira berapa banyak halaman dilawati — merangkak 100 halaman berharga sama seperti merangkak 5. Panggilan gagal tidak dicaj.

Pecahan Kos:

Sebarang perangkakan, 1 hingga 100 halaman: 4 credits

Cadangan Pelan:

Pelan Free: 1,000 credits percubaan sekali sahaja = 250 perangkakan

Pelan Hobby: 5,000 credits/bulan = 1,250 perangkakan ($19/bulan)

Pelan Professional: 100,000 credits/bulan = 25,000 perangkakan ($99/bulan)

Kerana kosnya rata, utamakan satu perangkakan dengan max_pages yang tinggi berbanding beberapa perangkakan kecil pada laman yang sama.

Alat Berkaitan

map_site

Temui URL tanpa melawati setiap halaman (2 credits)

extract_links

Dapatkan URL pautan sebenar daripada satu halaman (1 credit)

batch_scrape

Ekstrak kandungan daripada URL yang ditemui oleh perangkakan (5 credits setiap URL)

scrape

Pengekstrakan kandungan penuh daripada satu halaman (2 credits)

Bersedia mencuba crawl_deep? Daftar secara percuma dan dapatkan 1,000 credits untuk memetakan laman pertama anda.