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

Alat web fetch saat ini dalam versi beta. Untuk mengaktifkannya, gunakan header beta web-fetch-2025-09-10 dalam permintaan API Anda.

Silakan gunakan formulir ini untuk memberikan umpan balik tentang kualitas respons model, API itu sendiri, atau kualitas dokumentasi.

Mengaktifkan alat web fetch dalam lingkungan di mana Claude memproses input yang tidak terpercaya bersamaan dengan data sensitif menimbulkan risiko eksfiltrasi data. Kami merekomendasikan hanya menggunakan alat ini dalam lingkungan terpercaya atau saat menangani data yang tidak sensitif.

Untuk meminimalkan risiko eksfiltrasi, Claude tidak diizinkan untuk membuat URL secara dinamis. Claude hanya dapat mengambil URL yang telah disediakan secara eksplisit oleh pengguna atau yang berasal dari hasil pencarian web atau web fetch sebelumnya. Namun, masih ada risiko sisa yang harus dipertimbangkan dengan hati-hati saat menggunakan alat ini.

Jika eksfiltrasi data menjadi perhatian, pertimbangkan:

  • Menonaktifkan alat web fetch sepenuhnya
  • Menggunakan parameter max_uses untuk membatasi jumlah permintaan
  • Menggunakan parameter allowed_domains untuk membatasi ke domain yang diketahui aman

​
Model yang didukung

Web fetch tersedia pada:

  • Claude Opus 4.1 (claude-opus-4-1-20250805)
  • Claude Opus 4 (claude-opus-4-20250514)
  • Claude Sonnet 4 (claude-sonnet-4-20250514)
  • Claude Sonnet 3.7 (claude-3-7-sonnet-20250219)
  • Claude Sonnet 3.5 v2 (tidak digunakan lagi) (claude-3-5-sonnet-latest)
  • Claude Haiku 3.5 (claude-3-5-haiku-latest)

​
Cara kerja web fetch

Ketika Anda menambahkan alat web fetch ke permintaan API Anda:

  1. Claude memutuskan kapan mengambil konten berdasarkan prompt dan URL yang tersedia.
  2. API mengambil konten teks lengkap dari URL yang ditentukan.
  3. Untuk PDF, ekstraksi teks otomatis dilakukan.
  4. Claude menganalisis konten yang diambil dan memberikan respons dengan kutipan opsional.

​
Cara menggunakan web fetch

Sediakan alat web fetch dalam permintaan API Anda:

curl https://api.anthropic.com/v1/messages \
    --header "x-api-key: $ANTHROPIC_API_KEY" \
    --header "anthropic-version: 2023-06-01" \
    --header "anthropic-beta: web-fetch-2025-09-10" \
    --header "content-type: application/json" \
    --data '{
        "model": "claude-opus-4-1-20250805",
        "max_tokens": 1024,
        "messages": [
            {
                "role": "user",
                "content": "Silakan analisis konten di https://example.com/article"
            }
        ],
        "tools": [{
            "type": "web_fetch_20250910",
            "name": "web_fetch",
            "max_uses": 5
        }]
    }'

​
Definisi alat

Alat web fetch mendukung parameter berikut:

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

  // Opsional: Batasi jumlah fetch per permintaan
  "max_uses": 10,

  // Opsional: Hanya fetch dari domain ini
  "allowed_domains": ["example.com", "docs.example.com"],

  // Opsional: Jangan pernah fetch dari domain ini
  "blocked_domains": ["private.example.com"],

  // Opsional: Aktifkan kutipan untuk konten yang diambil
  "citations": {
    "enabled": true
  },

  // Opsional: Panjang konten maksimum dalam token
  "max_content_tokens": 100000
}

​
Max uses

Parameter max_uses membatasi jumlah web fetch yang dilakukan. Jika Claude mencoba melakukan fetch lebih dari yang diizinkan, web_fetch_tool_result akan menjadi error dengan kode error max_uses_exceeded. Saat ini tidak ada batas default.

​
Penyaringan domain

Saat menggunakan filter domain:

  • Domain tidak boleh menyertakan skema HTTP/HTTPS (gunakan example.com bukan https://example.com)
  • Subdomain secara otomatis disertakan (example.com mencakup docs.example.com)
  • Subpath didukung (example.com/blog)
  • Anda dapat menggunakan allowed_domains atau blocked_domains, tetapi tidak keduanya dalam permintaan yang sama.

Waspadai bahwa karakter Unicode dalam nama domain dapat menciptakan kerentanan keamanan melalui serangan homograf, di mana karakter yang secara visual mirip dari skrip yang berbeda dapat melewati filter domain. Misalnya, аmazon.com (menggunakan ‘а’ Cyrillic) mungkin tampak identik dengan amazon.com tetapi mewakili domain yang berbeda.

Saat mengonfigurasi daftar allow/block domain:

  • Gunakan nama domain khusus ASCII bila memungkinkan
  • Pertimbangkan bahwa parser URL mungkin menangani normalisasi Unicode secara berbeda
  • Uji filter domain Anda dengan variasi homograf potensial
  • Audit konfigurasi domain Anda secara berkala untuk karakter Unicode yang mencurigakan

​
Batas konten

Parameter max_content_tokens membatasi jumlah konten yang akan disertakan dalam konteks. Jika konten yang diambil melebihi batas ini, konten akan dipotong. Ini membantu mengontrol penggunaan token saat mengambil dokumen besar.

Batas parameter max_content_tokens adalah perkiraan. Jumlah token input aktual yang digunakan dapat bervariasi dalam jumlah kecil.

​
Kutipan

Tidak seperti pencarian web di mana kutipan selalu diaktifkan, kutipan bersifat opsional untuk web fetch. Atur "citations": {"enabled": true} untuk memungkinkan Claude mengutip bagian tertentu dari dokumen yang diambil.

Saat menampilkan hasil web atau informasi yang terkandung dalam hasil web kepada pengguna akhir, kutipan inline harus dibuat terlihat jelas dan dapat diklik dalam antarmuka pengguna Anda.

​
Respons

Berikut adalah contoh struktur respons:

{
  "role": "assistant",
  "content": [
    // 1. Keputusan Claude untuk fetch
    {
      "type": "text",
      "text": "Saya akan mengambil konten dari artikel untuk menganalisisnya."
    },
    // 2. Permintaan fetch
    {
      "type": "server_tool_use",
      "id": "srvtoolu_01234567890abcdef",
      "name": "web_fetch",
      "input": {
        "url": "https://example.com/article"
      }
    },
    // 3. Hasil fetch
    {
      "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": "Konten teks lengkap artikel..."
          },
          "title": "Judul Artikel",
          "citations": {"enabled": true}
        },
        "retrieved_at": "2025-08-25T10:30:00Z"
      }
    },
    // 4. Analisis Claude dengan kutipan (jika diaktifkan)
    {
      "text": "Berdasarkan artikel, ",
      "type": "text"
    },
    {
      "text": "argumen utama yang disajikan adalah bahwa kecerdasan buatan akan mengubah layanan kesehatan",
      "type": "text",
      "citations": [
        {
          "type": "char_location",
          "document_index": 0,
          "document_title": "Judul Artikel",
          "start_char_index": 1234,
          "end_char_index": 1456,
          "cited_text": "Kecerdasan buatan siap merevolusi penyampaian layanan kesehatan..."
        }
      ]
    }
  ],
  "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 meliputi:

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

Alat web fetch menyimpan hasil dalam cache untuk meningkatkan kinerja dan mengurangi permintaan yang berlebihan. Ini berarti konten yang dikembalikan mungkin tidak selalu versi terbaru yang tersedia di URL. Perilaku cache dikelola secara otomatis dan dapat berubah dari waktu ke waktu untuk mengoptimalkan berbagai jenis konten dan pola penggunaan.

Untuk dokumen PDF, konten akan dikembalikan sebagai data yang dikodekan 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, API Anthropic mengembalikan respons 200 (sukses) dengan error yang direpresentasikan dalam body respons:

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

Berikut adalah kode error yang mungkin:

  • invalid_input: Format URL tidak valid
  • url_too_long: URL melebihi panjang maksimum (250 karakter)
  • url_not_allowed: URL diblokir oleh aturan penyaringan domain dan pembatasan model
  • url_not_accessible: Gagal mengambil konten (error HTTP)
  • too_many_requests: Batas rate terlampaui
  • unsupported_content_type: Jenis konten tidak didukung (hanya teks dan PDF)
  • max_uses_exceeded: Penggunaan alat web fetch maksimum terlampaui
  • unavailable: Terjadi error internal

​
Validasi URL

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

  • 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 arbitrer yang dihasilkan Claude atau URL dari alat server berbasis kontainer (Code Execution, Bash, dll.).

​
Pencarian dan fetch gabungan

Web fetch bekerja dengan mulus dengan pencarian web untuk pengumpulan informasi yang komprehensif:

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=4096,
    messages=[
        {
            "role": "user",
            "content": "Temukan artikel terbaru tentang komputasi kuantum dan analisis yang paling relevan secara 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}
        }
    ],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

Dalam alur kerja ini, Claude akan:

  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 detail dengan kutipan

​
Prompt caching

Web fetch bekerja dengan prompt caching. Untuk mengaktifkan prompt caching, tambahkan breakpoint cache_control dalam permintaan Anda. Hasil fetch yang di-cache dapat digunakan kembali di seluruh giliran percakapan.

import anthropic

client = anthropic.Anthropic()

# Permintaan pertama dengan web fetch
messages = [
    {
        "role": "user",
        "content": "Analisis makalah penelitian ini: https://arxiv.org/abs/2024.12345"
    }
]

response1 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Tambahkan respons Claude ke percakapan
messages.append({
    "role": "assistant",
    "content": response1.content
})

# Permintaan kedua dengan breakpoint cache
messages.append({
    "role": "user",
    "content": "Metodologi apa yang digunakan makalah tersebut?",
    "cache_control": {"type": "ephemeral"}
})

response2 = client.messages.create(
    model="claude-opus-4-1-20250805",
    max_tokens=1024,
    messages=messages,
    tools=[{
        "type": "web_fetch_20250910",
        "name": "web_fetch"
    }],
    extra_headers={
        "anthropic-beta": "web-fetch-2025-09-10"
    }
)

# Respons kedua mendapat manfaat dari hasil fetch yang di-cache
print(f"Token baca cache: {response2.usage.get('cache_read_input_tokens', 0)}")

​
Streaming

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

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": ""}}

// Keputusan Claude untuk fetch

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

// URL fetch di-stream
event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "input_json_delta", "partial_json": "{\"url\":\"https://example.com/article\"}"}}

// Jeda saat fetch dieksekusi

// Hasil fetch di-stream
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": "Konten artikel..."}}}}}

// Respons Claude berlanjut...

​
Permintaan batch

Anda dapat menyertakan alat web fetch dalam Messages Batches API. Panggilan alat web fetch melalui Messages Batches API dihargai sama dengan yang ada dalam permintaan Messages API biasa.

​
Penggunaan dan harga

Web fetch usage has no additional charges beyond standard token costs:

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

The web fetch tool is available on the Anthropic API at no additional cost. You only pay standard token costs for the fetched content that becomes part of your conversation context.

To protect against inadvertently fetching large content that would consume excessive tokens, use the max_content_tokens parameter to set appropriate limits based on your use case and budget considerations.

Example token usage for typical content:

  • Average web page (10KB): ~2,500 tokens
  • Large documentation page (100KB): ~25,000 tokens
  • Research paper PDF (500KB): ~125,000 tokens