Alat web fetch

Alat web fetch memungkinkan Claude mengambil konten lengkap dari halaman web dan dokumen PDF yang ditentukan.

Versi terbaru alat web fetch (web_fetch_20260318) mendukung dynamic filtering (pemfilteran dinamis): Claude dapat menulis dan mengeksekusi kode untuk memfilter konten yang diambil sebelum konten tersebut mencapai "context window" (jendela konteks). Dengan begitu, hanya informasi yang relevan yang disimpan dan sisanya dibuang. Hal ini mengurangi konsumsi token sambil tetap menjaga kualitas respons. Pemfilteran dinamis tersedia untuk model Claude 4.6 dan yang lebih baru serta Claude Mythos Preview. web_fetch_20260318 juga menambahkan kontrol penyertaan respons untuk alur kerja agentik. Versi-versi sebelumnya tetap tersedia: web_fetch_20260309 untuk pemfilteran dinamis dan bypass cache, web_fetch_20260209 khusus untuk pemfilteran dinamis, dan web_fetch_20250910 untuk fetch dasar.

Web fetch (dengan maupun tanpa pemfilteran dinamis) tersedia di Claude API, Claude Platform on AWS, dan Microsoft Foundry. Di Microsoft Foundry, deployment yang di-hosting di Azure hanya mendukung alat web fetch dasar (web_fetch_20250910, tanpa pemfilteran dinamis). Deployment yang di-hosting di Anthropic mendukung semua versi. Web fetch saat ini belum tersedia di Amazon Bedrock atau Google Cloud.

Untuk kelayakan Zero Data Retention dan solusi alternatif allowed_callers, lihat Alat server.

Untuk dukungan model, lihat Referensi alat.

Cara kerja web fetch

Web fetch adalah sebuah alat server: API mengambil konten selama permintaan berlangsung dan menyisipkan hasilnya ke dalam percakapan. Anda tidak perlu menjalankan apa pun atau mengembalikan tool_result. Pengecualiannya adalah ketika Claude memanggil web fetch dan salah satu alat klien Anda dalam kelompok pemanggilan alat paralel yang sama. Dalam kasus ini, API mengembalikan respons dengan stop_reason: "tool_use" sebelum fetch tersebut dijalankan, lalu menjalankan fetch setelah Anda mengirimkan kembali blok tool_result klien. Lihat Menggabungkan alat server dan alat klien dalam satu giliran.

Saat Anda menambahkan alat web fetch ke permintaan API Anda:

1. Claude menentukan kapan harus mengambil konten berdasarkan prompt dan URL yang tersedia.
2. API mengambil konten teks lengkap dari URL yang ditentukan.
3. Untuk PDF, API mengembalikan konten sebagai data berenkode base64 dan memprosesnya seperti dokumen PDF yang dilampirkan secara langsung.
4. Claude menganalisis konten yang diambil dan memberikan respons, opsional dengan sitasi.

Kapan Claude melakukan fetch

Claude melakukan fetch ketika permintaan merujuk ke halaman atau dokumen tertentu:

• Sebuah URL diberikan dalam percakapan (atau dalam hasil alat sebelumnya)
• Pengguna menyebutkan sumber daya tertentu (artikel, README, halaman harga, atau bagian dokumentasi tertentu) tanpa URL, dan alat web search juga diaktifkan sehingga Claude dapat menemukannya terlebih dahulu (lihat Gabungan search dan fetch)

Claude tidak melakukan fetch untuk pertanyaan pengetahuan umum atau pertanyaan terbuka yang tidak merujuk ke halaman tertentu. "Ringkas artikel ini: <url>" akan memicu fetch. "Apa praktik terbaik untuk desain REST API?" akan dijawab secara langsung.

Pemfilteran dinamis

Mengambil halaman web dan PDF secara utuh dapat menghabiskan token dengan cepat, terutama ketika Anda hanya membutuhkan informasi tertentu dari dokumen berukuran besar. Dengan web_fetch_20260209 atau versi yang lebih baru, Claude dapat menulis dan mengeksekusi kode untuk memfilter konten yang diambil sebelum memuatnya ke dalam konteks.

Pemfilteran dinamis ini sangat berguna untuk:

• Mengekstrak bagian tertentu dari dokumen panjang
• Memproses data terstruktur dari halaman web
• Memfilter informasi yang relevan dari PDF
• Mengurangi biaya token saat bekerja dengan dokumen berukuran besar

Untuk mengaktifkan pemfilteran dinamis, gunakan web_fetch_20260209 atau versi apa pun yang lebih baru. Contoh-contoh berikut menggunakan web_fetch_20260318:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Fetch the content at https://example.com/research-paper and extract the key findings.",
        }
    ],
    tools=[{"type": "web_fetch_20260318", "name": "web_fetch"}],
)
print(response)

Cara menggunakan web fetch

Sertakan alat web fetch dalam permintaan API Anda:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Please analyze the content at https://example.com/article",
        }
    ],
    tools=[{"type": "web_fetch_20250910", "name": "web_fetch", "max_uses": 5}],
)
print(response)

Definisi alat

Alat web fetch mendukung parameter-parameter berikut:

{
  "type": "web_fetch_20250910",
  "name": "web_fetch",

  // Optional: Limit the number of fetches per request
  "max_uses": 10,

  // Optional: Only fetch from these domains
  "allowed_domains": ["example.com", "docs.example.com"],

  // Optional: Never fetch from these domains (cannot be combined with allowed_domains)
  "blocked_domains": ["private.example.com"],

  // Optional: Enable citations for fetched content
  "citations": {
    "enabled": true
  },

  // Optional: Maximum content length in tokens
  "max_content_tokens": 100000
}

Versi alat yang lebih baru menambahkan dua parameter opsional lagi: use_cache memerlukan web_fetch_20260309 atau yang lebih baru (lihat Bypass cache), dan response_inclusion memerlukan web_fetch_20260318 atau yang lebih baru (lihat Penyertaan respons).

Penggunaan maksimum

Parameter max_uses membatasi jumlah web fetch yang dilakukan. Fetch yang gagal tetap dihitung terhadap batas ini. Jika Claude mencoba melakukan fetch melebihi jumlah yang diizinkan, web_fetch_tool_result akan berupa error dengan kode error max_uses_exceeded. Saat ini tidak ada batas default.

Pemfilteran domain

Untuk pemfilteran domain dengan allowed_domains dan blocked_domains, lihat Alat server.

Di Claude Managed Agents, atur field-field ini pada entri web_fetch di toolset agen. Setiap domain yang dicantumkan harus berupa hostname biasa tanpa path. Lihat Membatasi domain web search dan web fetch.

Batas konten

Parameter max_content_tokens membatasi jumlah konten yang disertakan dalam konteks. Jika konten yang diambil melebihi batas ini, alat akan memotongnya. Hal ini membantu mengendalikan penggunaan token saat mengambil dokumen berukuran besar. Batas ini berlaku untuk konten teks, bukan untuk konten biner seperti PDF.

Di Claude Managed Agents, entri web_fetch di toolset agen juga menerima max_content_tokens. Lihat Membatasi domain web search dan web fetch.

Bypass cache

Parameter use_cache mengontrol apakah konten yang di-cache boleh dikembalikan. Atur "use_cache": false untuk melewati cache dan mengambil konten terbaru. Nilai default-nya adalah true. Nonaktifkan caching hanya ketika pengguna secara eksplisit meminta konten terbaru atau ketika mengambil sumber yang berubah dengan cepat, karena melewati cache akan meningkatkan "latency" (latensi).

{
  "tools": [
    {
      "type": "web_fetch_20260309",
      "name": "web_fetch",
      "use_cache": false
    }
  ]
}

Penyertaan respons

Parameter response_inclusion mengontrol cara blok hasil fetch ditampilkan dalam respons API ketika hasil tersebut telah digunakan oleh pemanggilan code execution yang sudah selesai dalam giliran yang sama. Atur "response_inclusion": "excluded" untuk menghapus seluruh pasangan blok server_tool_use dan blok hasil yang bersarang tersebut dari respons. Cara ini mengurangi biaya token output untuk alur kerja agentik yang tidak perlu mengirimkan kembali konten halaman mentah ke klien. Nilai default-nya adalah "full". Hasil dari pemanggilan langsung, atau dari pemanggilan code execution yang dijeda sebelum selesai, selalu dikembalikan secara lengkap agar dapat dikirim kembali pada giliran berikutnya.

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "response_inclusion": "excluded"
    }
  ]
}

Sitasi

Berbeda dengan web search yang sitasinya selalu diaktifkan, sitasi pada web fetch bersifat opsional dan dinonaktifkan secara default. Atur "citations": {"enabled": true} agar Claude dapat mengutip bagian tertentu dari dokumen yang diambil.

Respons

Berikut contoh struktur respons:

{
  "role": "assistant",
  "content": [
    // 1. Claude's decision to fetch
    {
      "type": "text",
      "text": "I'll fetch the content from the article to analyze it."
    },
    // 2. The fetch request
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Fetch results
    {
      "type": "web_fetch_tool_result",
      "tool_use_id": "srvtoolu_01234567890abcdef",
      "content": {
        "type": "web_fetch_result",
        "url": "https://example.com/article",
        "content": {
          "type": "document",
          "source": {
            "type": "text",
            "media_type": "text/plain",
            "data": "Full text content of the article..."
          },
          "title": "Article Title",
          "citations": { "enabled": true }
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Claude's analysis with citations (if enabled)
    {
      "text": "Based on the article, ",
      "type": "text"
    },
    {
      "text": "the main argument presented is that artificial intelligence will transform healthcare",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Article Title",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Artificial intelligence is poised to revolutionize healthcare delivery..."
        }
      ]
    }
  ],
  "id": "msg_a930390d3a",
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  },
  "stop_reason": "end_turn"
}

Hasil fetch

Hasil fetch mencakup:

• url: URL yang diambil
• content: Blok dokumen yang berisi konten yang diambil
• retrieved_at: Timestamp saat konten diambil

Untuk dokumen PDF, konten dikembalikan sebagai data berenkode base64:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_02",
  "content": {
    "type": "web_fetch_result",
    "url": "https://example.com/paper.pdf",
    "content": {
      "type": "document",
      "source": {
        "type": "base64",
        "media_type": "application/pdf",
        "data": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmo..."
      },
      "citations": { "enabled": true }
    },
    "retrieved_at": "2025-08-25T10:30:02Z"
  }
}

Error

Ketika alat web fetch mengalami error, Claude API mengembalikan respons 200 (sukses) dengan error yang dinyatakan di dalam body respons. Claude melihat hasil error tersebut dan melanjutkan gilirannya. Contohnya:

{
  "type": "web_fetch_tool_result",
  "tool_use_id": "srvtoolu_a93jad",
  "content": {
    "type": "web_fetch_tool_result_error",
    "error_code": "url_not_accessible"
  }
}

Berikut kode-kode error yang mungkin muncul:

• invalid_tool_input: Input alat tidak valid, seperti URL yang formatnya salah atau skema selain HTTP(S)
• url_too_long: URL melebihi panjang maksimum (250 karakter)
• url_not_allowed: URL diblokir oleh aturan pemfilteran domain (termasuk pengaturan organisasi Anda) atau oleh pembatasan dari sisi Anthropic, seperti alamat privat, robots.txt, dan URL yang tampaknya berisi kredensial yang tidak Anda berikan
• url_not_in_prior_context: URL tidak muncul sebelumnya dalam percakapan (lihat Validasi URL)
• url_not_accessible: Gagal mengambil konten (error HTTP)
• too_many_requests: Batas laju terlampaui
• unsupported_content_type: Jenis konten tidak didukung (hanya teks, HTML, dan PDF)
• max_uses_exceeded: Jumlah penggunaan maksimum alat web fetch terlampaui
• unavailable: Terjadi error internal

Validasi URL

Demi alasan keamanan, alat web fetch hanya dapat mengambil URL yang sebelumnya sudah muncul dalam konteks percakapan. Ini mencakup:

• URL dalam pesan pengguna
• URL dalam hasil alat sisi klien
• URL dari hasil web search atau web fetch sebelumnya

Alat ini tidak dapat mengambil URL yang hanya muncul dalam output Claude sendiri atau hanya dalam prompt sistem. Agar URL dari prompt sistem dapat diambil, sertakan juga URL tersebut dalam pesan pengguna. Hasil dari alat sisi server lainnya, seperti code execution, konektor MCP, atau tool search, juga tidak termasuk sumber yang diizinkan. Hasil alat sisi klien tetap merupakan sumber yang diizinkan meskipun mengulang teks yang dihasilkan Claude (misalnya, perintah yang mencetak inputnya, atau pesan error yang mengutipnya).

Alat ini juga menolak URL yang tampaknya berisi kredensial, seperti kunci API atau kata sandi, kecuali kredensial tersebut muncul dalam prompt sistem atau dalam teks pesan pengguna. Kredensial yang hanya muncul dalam hasil alat tidak dihitung. Hasilnya adalah error url_not_allowed. Untuk mengambil URL seperti itu, sertakan URL tersebut dalam pesan pengguna.

Gabungan search dan fetch

Ketika alat web search dan web fetch sama-sama diaktifkan, dan pengguna menyebutkan halaman atau dokumen tertentu tanpa memberikan URL (misalnya, "baca README dari repositori anthropics/anthropic-sdk-python"), Claude menggunakan web search untuk menemukannya, lalu mengambil hasilnya. Contoh berikut meminta pencarian sekaligus analisis dalam satu permintaan:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Find recent articles about quantum computing and analyze the most relevant one in detail",
        }
    ],
    tools=[
        {"type": "web_search_20250305", "name": "web_search", "max_uses": 3},
        {
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5,
            "citations": {"enabled": True},
        },
    ],
)
print(response)

Dalam alur kerja ini, Claude:

1. Menggunakan web search untuk menemukan artikel yang relevan.
2. Memilih hasil yang paling menjanjikan.
3. Menggunakan web fetch untuk mengambil konten lengkap.
4. Memberikan analisis mendetail beserta sitasi.

Caching prompt

Untuk menyimpan definisi alat dalam cache di sepanjang giliran, lihat Penggunaan alat dengan caching prompt.

Streaming

Saat streaming diaktifkan, event fetch menjadi bagian dari stream, dengan jeda selama pengambilan konten berlangsung:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_abc123", "type": "message"}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}}

// Claude's decision to fetch

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "server_tool_use", "id": "srvtoolu_xyz789", "name": "web_fetch"}}

// Fetch URL streamed
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Pause while fetch executes

// Fetch results streamed
event: content_block_start
data: {"type": "content_block_start", "index": 2, "content_block": {"type": "web_fetch_tool_result", "tool_use_id": "srvtoolu_xyz789", "content": {"type": "web_fetch_result", "url": "https://example.com/article", "content": {"type": "document", "source": {"type": "text", "media_type": "text/plain", "data": "Article content..."}}}}}

// Claude's response continues...

Permintaan batch

Anda dapat menyertakan alat web fetch dalam Messages Batches API. Pemanggilan alat web fetch melalui Messages Batches API dikenakan harga yang sama dengan pemanggilan dalam permintaan Messages API biasa.

Penggunaan dan harga

Penggunaan web fetch tidak dikenakan biaya tambahan di luar biaya token standar:

{
  "usage": {
    "input_tokens": 25039,
    "output_tokens": 931,
    "cache_read_input_tokens": 0,
    "cache_creation_input_tokens": 0,
    "server_tool_use": {
      "web_fetch_requests": 1
    }
  }
}

Alat web fetch tersedia di Claude API tanpa biaya tambahan. Anda hanya membayar biaya token standar untuk konten yang diambil yang menjadi bagian dari konteks percakapan Anda.

Untuk melindungi dari pengambilan konten besar secara tidak sengaja yang akan menghabiskan token secara berlebihan, gunakan parameter max_content_tokens untuk menetapkan batas yang sesuai berdasarkan kasus penggunaan dan pertimbangan anggaran Anda.

Contoh penggunaan token untuk konten umum:

• Halaman web rata-rata (10 kB): ~2.500 token
• Halaman dokumentasi besar (100 kB): ~25.000 token
• PDF makalah penelitian (500 kB): ~125.000 token

Langkah selanjutnya