Claude Platform Docs
PesanAlat

Alat web fetch

Ambil dan baca konten dari URL tertentu untuk memperkaya konteks Claude dengan konten web langsung.

Penggunaan berbeda menurut produk

Messages API
Tambahkan alat web_fetch ke tools permintaan.
Managed Agents
Aktif secara default dalam toolset agen, tanpa max_uses, citations, atau cache_control.

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 menjalankan kode untuk memfilter konten yang diambil sebelum mencapai “context window” (jendela konteks), sehingga hanya informasi yang relevan yang disimpan dan sisanya dibuang. Ini mengurangi konsumsi token sambil mempertahankan kualitas respons. Pemfilteran dinamis tersedia dengan model Claude 4.6 dan yang lebih baru serta Claude Mythos Preview. web_fetch_20260318 juga menambahkan kontrol “response inclusion” (penyertaan respons) untuk alur kerja agentik. Versi lainnya (web_fetch_20260309 untuk pemfilteran dinamis dan melewati cache, web_fetch_20260209 hanya untuk pemfilteran dinamis, web_fetch_20250910 untuk fetch dasar) tersedia.

Web fetch (dengan dan tanpa pemfilteran dinamis) tersedia di Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), dan Microsoft Foundry. Di Microsoft Foundry, deployment yang di-host di Azure hanya mendukung alat web fetch dasar (web_fetch_20250910, tanpa pemfilteran dinamis). Deployment yang di-host di Anthropic mendukung semua versi.

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

Untuk dukungan model, lihat Referensi alat.

Cara kerja web fetch

Web fetch adalah alat server: API mengambil konten selama permintaan dan menyisipkan hasilnya ke dalam percakapan. Anda tidak menjalankan apa pun atau mengembalikan tool_result. Pengecualiannya adalah ketika Claude memanggil web fetch dan salah satu alat klien Anda dalam grup panggilan alat paralel yang sama: API mengembalikan respons dengan stop_reason: "tool_use" sebelum fetch tersebut dijalankan, lalu menjalankan fetch saat Anda mengirim kembali blok tool_result klien. Lihat Mencampur 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 yang dienkode base64 dan memprosesnya seperti dokumen PDF yang dilampirkan langsung.
  4. Claude menganalisis konten yang diambil dan memberikan respons dengan sitasi opsional.

Kapan Claude melakukan fetch

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

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

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

Pemfilteran dinamis

Mengambil halaman web dan PDF lengkap dapat dengan cepat menghabiskan token, terutama ketika hanya informasi tertentu yang dibutuhkan dari dokumen besar. Dengan web_fetch_20260209 atau yang lebih baru, Claude dapat menulis dan menjalankan 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 besar

Untuk mengaktifkan pemfilteran dinamis, gunakan web_fetch_20260209 atau versi yang lebih baru. 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

Untuk cara pengaturan web fetch organisasi Anda diterapkan dalam sesi Claude Managed Agents, lihat Membatasi domain pencarian web dan web fetch.

Sediakan alat web fetch dalam permintaan API Anda:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    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 berikut:

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

  // Optional: Limit the number of fetches
  "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: Don't fetch URLs that appear only in client-side tool results
  "url_sources": {
    "client_tool_results": { "type": "none" }
  },

  // 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 Melewati cache), dan response_inclusion memerlukan web_fetch_20260318 atau yang lebih baru (lihat Penyertaan respons).

Penggunaan maksimum

Parameter max_uses membatasi jumlah web fetch dalam satu giliran. Fetch yang gagal dihitung terhadap batas tersebut. Jika Claude memanggil web fetch secara langsung lebih banyak dari yang diizinkan, web_fetch_tool_result akan berupa error dengan kode error max_uses_exceeded. Jika Claude memanggil web fetch dari eksekusi kode lebih banyak dari yang diizinkan, proses eksekusi kode berakhir dengan error. Tidak ada batas default.

Satu giliran dapat mencakup beberapa permintaan. Sebuah permintaan melanjutkan giliran ketika permintaan tersebut dilanjutkan setelah pause_turn atau ketika pesan terakhirnya hanya berisi blok tool_result. Fetch dari permintaan sebelumnya dalam giliran tersebut dihitung terhadap batas, kecuali Claude menjalankannya dari eksekusi kode melalui pemfilteran dinamis.

Pemfilteran domain

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

Di Claude Managed Agents, tetapkan field ini pada entri web_fetch dari toolset agen; lihat Membatasi domain pencarian web 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. Ini membantu mengontrol penggunaan token saat mengambil dokumen besar. Batas ini bersifat perkiraan: jumlah sebenarnya token input yang digunakan dapat sedikit bervariasi. Batas ini berlaku untuk konten teks, bukan untuk konten biner seperti PDF.

Jika PDF yang diambil akan membuat permintaan melebihi batas halaman atau ukuran PDF, web_fetch_tool_result akan berupa error dengan kode error content_too_large. PDF dan gambar yang sudah ada dalam percakapan dihitung terhadap batas tersebut, sehingga menghapusnya dapat membuat fetch berhasil.

Di Claude Managed Agents, entri web_fetch dari toolset agen juga menerima max_content_tokens; lihat pengaturan alat web.

Melewati cache

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

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

Penyertaan respons

Parameter response_inclusion mengontrol bagaimana blok hasil fetch muncul dalam respons API ketika hasilnya dikonsumsi oleh panggilan eksekusi kode yang telah selesai dalam respons yang sama. Tetapkan "response_inclusion": "excluded" untuk menghapus pasangan blok server_tool_use dan blok hasil bersarang tersebut sepenuhnya dari respons, untuk alur kerja agentik yang tidak memerlukan konten halaman mentah. Penggunaan token tidak terpengaruh, karena Claude membaca output kode, bukan blok-blok ini. Default-nya adalah "full". API selalu mengembalikan hasil dari panggilan langsung, atau dari panggilan eksekusi kode yang dijeda sebelum selesai, secara lengkap sehingga Anda dapat mengirimkannya kembali pada permintaan berikutnya.

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

Sitasi

Berbeda dengan pencarian web, di mana sitasi selalu diaktifkan, sitasi bersifat opsional untuk web fetch dan dinonaktifkan secara default. Tetapkan "citations": {"enabled": true} untuk memungkinkan Claude mengutip bagian tertentu dari dokumen yang diambil.

Respons

Berikut adalah contoh struktur respons:

Output
{
  "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 yang dienkode base64:

Output
{
  "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 direpresentasikan dalam body respons. Claude menerima hasil error tersebut dan melanjutkan giliran. Contohnya:

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

Berikut adalah kode error yang mungkin:

  • invalid_tool_input: Input alat tidak valid, seperti URL yang formatnya salah atau skema non-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, atau hanya muncul di sumber yang dikecualikan oleh url_sources (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)
  • content_too_large: PDF yang diambil akan membuat permintaan melebihi batas halaman atau ukuran PDF (lihat Batas konten)
  • max_uses_exceeded: Penggunaan maksimum alat web fetch terlampaui
  • unavailable: Terjadi error internal

Validasi URL

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

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

Alat ini tidak dapat mengambil URL yang hanya muncul di output Claude sendiri atau hanya di prompt sistem. Agar URL dari prompt sistem dapat diambil, sertakan juga URL tersebut dalam pesan pengguna. Hasil dari alat sisi server lainnya, seperti eksekusi kode, konektor MCP, atau pencarian alat, juga bukan sumber yang diizinkan. Secara default, hasil alat sisi klien adalah sumber yang diizinkan bahkan ketika hasil tersebut 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 di prompt sistem atau di 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.

Sumber URL

Parameter opsional url_sources memungkinkan Anda menonaktifkan salah satu dari tiga sumber yang diizinkan, atau membatasi hasil alat ke alat tertentu. Parameter ini memiliki satu kunci untuk setiap sumber, dan setiap kunci memiliki default {"type": "all"}:

  • user_input: URL dalam pesan pengguna. type-nya adalah "all" atau "none".
  • client_tool_results: URL dalam hasil alat sisi klien. type-nya adalah "all", "none", atau filter "only" atau "except" yang menyebutkan nama alat, seperti dalam contoh berikut.
  • server_tool_results: URL dari hasil pencarian web atau web fetch sebelumnya. Key ini menerima nilai yang sama, dan filternya menyebutkan web_search atau web_fetch.

Misalnya, alat yang menjalankan kode yang ditulis Claude mengembalikan apa pun yang dicetak oleh kode tersebut, termasuk URL apa pun yang dimasukkan Claude ke dalamnya. Untuk menghentikan hasil alat tersebut agar tidak dihitung sebagai sumber, sebutkan alat tersebut dalam filter "except":

{
  "tools": [
    {
      "type": "web_fetch_20260318",
      "name": "web_fetch",
      "url_sources": {
        "client_tool_results": {
          "type": "except",
          "tools": [{ "type": "tool_reference", "name": "run_code" }]
        }
      }
    },
    {
      "name": "run_code",
      "description": "Run Python code and return its output",
      "input_schema": {
        "type": "object",
        "properties": { "code": { "type": "string" } },
        "required": ["code"]
      }
    }
  ]
}

Filter mencantumkan alat sebagai objek tool_reference. Setiap nama harus cocok dengan alat dalam array tools pada permintaan: alat klien untuk client_tool_results, atau alat server untuk server_tool_results. Jika tidak, permintaan gagal dengan error. Di bawah "except", alat yang Anda tambahkan ke tools kemudian dihitung sebagai sumber. Di bawah "only", alat tersebut tidak dihitung.

Alat sisi klien selain run_code juga dapat mengembalikan teks yang ditulis Claude, misalnya dalam pesan error yang mengutipnya. Untuk mengecualikan semua hasil alat sisi klien, tetapkan client_tool_results ke {"type": "none"}.

Jika URL hanya muncul di sumber yang dikecualikan oleh url_sources, mengambilnya akan mengembalikan error url_not_in_prior_context.

Gabungan pencarian dan fetch

Ketika alat pencarian web 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 pencarian web untuk menemukannya, lalu mengambil hasilnya. Contoh berikut meminta pencarian dan 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 pencarian web untuk menemukan artikel yang relevan.
  2. Memilih hasil yang paling menjanjikan.
  3. Menggunakan web fetch untuk mengambil konten lengkap.
  4. Memberikan analisis terperinci dengan sitasi.

Caching prompt

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

Streaming

Dengan streaming diaktifkan, event fetch merupakan bagian dari stream dengan jeda selama pengambilan konten:

Output
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 runs

// 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 Message Batches API. Panggilan alat web fetch melalui Message Batches API dikenakan harga yang sama dengan panggilan 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

Jalankan kode Python dan Bash dalam container sandbox untuk menganalisis data, menghasilkan file, dan melakukan iterasi pada solusi.

Bekerja dengan alat yang dijalankan Anthropic: blok server_tool_use, kelanjutan pause_turn, dan pemfilteran domain.

Direktori alat yang disediakan Anthropic dan referensi untuk properti definisi alat opsional.

Ketersediaan

Alat web fetch
API
  • Messages API
  • Managed Agents
Model
  • Semua model

Endpoint yang berlaku

  • /v1/messages dengan alat web_fetch
Retensi data nolLayak

Tidak termasuk Model yang dicakup

Konten web yang diambil dikembalikan dalam respons API. Pemfilteran dinamis untuk web fetch tidak memenuhi syarat kelayakan ZDR atau HIPAA. Penerbit situs web mungkin menyimpan data permintaan (seperti URL yang diambil dan metadata permintaan) sesuai kebijakan mereka sendiri.

HIPAATidak layak

Apakah halaman ini membantu?