Claude Message Threads API: panduan thread

Claude message threads API memungkinkan Anda mengirim percakapan panjang sekali, lalu pada setiap giliran berikutnya hanya mengirim pesan baru. Tambahkan "thread": {"type": "create"} ke permintaan Messages pertama dan header beta message-threads-2026-08-12: API menyimpan percakapan di memori dan permintaan berikutnya mengirim lebih sedikit (halaman Message threads Anthropic, 4 November 2026).

Fitur ini beta di semua model. 17 ID model bisa memakainya, termasuk Claude Opus 5.5 yang dipanggil kode di bawah. Header beta ikut di setiap permintaan sebuah thread.

Apa yang dihemat thread

Tanpa thread, setiap giliran membawa seluruh transkrip: system prompt, definisi tool, semua pesan sebelumnya, dan semua hasil tool. Thread menyimpan percakapan itu beserta jawaban Claude di bawah id jawaban, dan permintaan continue hanya mengirim yang terjadi setelahnya (halaman Message threads, 4 November 2026). Lebih sedikit isi per giliran.

Cache prompt menolong percakapan yang sama dari sisi lain. Cache hit membuat input berulang lebih murah: di Opus 5.5, 0,20 USD per juta token dibanding 4 USD untuk input baru (halaman harga Anthropic, 4 November 2026). Permintaan tetap membawa input itu. Thread mengurangi yang Anda kirim; cache menurunkan harga yang berulang. Sesi panjang butuh keduanya, dan mengurangi pemakaian token Claude Code membahas sisi konteks.

Thread tidak mengubah harga maupun batas laju (halaman Message threads, 4 November 2026). Tarif terkini ada di halaman harga.

Cache Anda yang atur. Kirim cache_control tingkat atas di setiap permintaan dan API menerapkannya ke blok messages terakhir yang bisa di-cache pada permintaan itu. Batas empat breakpoint adalah aturan cache prompt seluruh platform, dan cache otomatis memakai satu dari empat (halaman cache prompt Anthropic, 4 November 2026). Bagikan seperti ini:

1. cache_control tingkat atas, satu titik di setiap permintaan thread;
2. satu di system, dikirim bersama permintaan create;
3. satu di tools, juga saat create;
4. satu di pesan terbaru.

Breakpoint pada pesan yang sudah tersimpan tidak masuk hitungan ini, karena permintaan continue hanya mengirim pesan baru. Breakpoint yang sudah dikirim tetap di tempatnya. Saat mengirim ulang percakapan, hapus titik pada pesan sebelumnya dan sisakan satu di blok terakhir (halaman Message threads, 4 November 2026).

Buat giliran pertama, lalu lanjutkan

Tiga langkah:

1. Taruh kunci Anthropic Anda di ANTHROPIC_API_KEY.
2. Kirim percakapan lengkap, dengan system dan tools jika Anda memakainya, plus "thread": {"type": "create"}.
3. Kirim hanya pesan sejak jawaban terakhir, plus "thread": {"type": "continue", "previous_message_id": "<previous id>"}, dan biarkan system serta tools di luar.

Setiap permintaan membawa header beta dan anthropic-version: 2026-10-21, versi saat ini (halaman versi Anthropic, 4 November 2026).

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 1024,
    "system": "You are a careful backend reviewer.",
    "messages": [
      {"role": "user", "content": "Read this design and list the risks."}
    ],
    "thread": {"type": "create"}
  }'

Simpan id dari jawaban itu. Permintaan berikutnya hanya mengirim pesan baru:

PREVIOUS_ID="<id from the previous response>"

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-10-21" \
  -H "anthropic-beta: message-threads-2026-08-12" \
  -H "content-type: application/json" \
  -d @- <<JSON
{
  "model": "claude-opus-5-5",
  "max_tokens": 1024,
  "messages": [
    {"role": "user", "content": "Turn those risks into a checklist."}
  ],
  "thread": {"type": "continue", "previous_message_id": "$PREVIOUS_ID"}
}
JSON

Simpan id terbaru dari setiap jawaban: thread hanya menerima tambahan, setiap id jawaban dilanjutkan sekali, dan permintaan berikutnya harus memakai yang terakhir (halaman Message threads, 4 November 2026).

Kalau Anda butuh jalur lain untuk kunci API, OmniaKey menjual akses ke API Claude dengan ID model yang sama, jadi body permintaan tidak berubah. Thread masih beta di sisi Anthropic, jadi sebelum bergantung padanya di produksi, periksa apakah perantara yang Anda pakai meneruskan field thread apa adanya.

SDK Python melacak id untuk Anda. Siapkan helper dengan client.beta.messages.thread(...), yang hanya menyiapkan panggilan, lalu kirim tiap giliran dengan thread.send(). Helper menambahkan header beta, membuat thread di giliran pertama, melanjutkan dengan pesan baru saja, dan sekali mengirim ulang percakapan lengkap dalam permintaan create baru ketika continue mengembalikan thread_not_found, thread_already_continued, atau thread_continue_in_flight (halaman Message threads, 4 November 2026).

import anthropic

client = anthropic.Anthropic()  # membaca ANTHROPIC_API_KEY

# Helper belum mengirim apa pun; ia menyimpan field yang dipakai ulang tiap giliran.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You are a careful backend reviewer.",
)

first = thread.send({"role": "user", "content": "Read this design and list the risks."})
print(first.id, first.stop_reason)

second = thread.send({"role": "user", "content": "Turn those risks into a checklist."})
print(second.id)  # lain kali lanjutkan dari id ini

Kami tidak menjalankan permintaan ini ke API Anthropic; bentuknya diambil dari halaman Message threads Anthropic. Untuk streaming, thread.stream(...) dan stream.get_final_message() memberi alur yang sama, dan thread.previous_message_id mengembalikan id kalau Anda lebih suka melacaknya sendiri.

Field mana yang dikirim ulang, mana yang tidak pernah

Kirim field tetap dengan nilai sama di setiap permintaan, system dan tools hanya di permintaan create, dan biarkan field bebas berubah antar giliran.

400 untuk field tetap yang berubah membawa thread_fingerprint_mismatch, dan pesannya mencantumkan field yang berbeda. Untuk mengubah nilai seperti itu, mulai thread baru dengan percakapan lengkap dan nilai baru.

Kalau previous_message_id hilang, permintaan continue mengembalikan 400 dengan message di body tetapi tanpa error_code; menambahkan system atau tools memberi hasil sama. Permintaan continue harus membawa tepat pesan sejak jawaban terakhir.

mcp_servers tetap, tetapi URL server dan token otorisasi hanya ada di permintaan Anda, jadi kirim daftarnya di setiap permintaan yang memakai MCP; token bisa berubah antar permintaan. id container juga hanya ada di permintaan Anda, jadi kirim container setiap kali (halaman Message threads, 4 November 2026).

Fallback sisi server ditentukan saat create: kirim fallbacks di setiap permintaan thread atau tidak sama sekali. Nilainya boleh berubah antar giliran, tetapi menambah atau menghapus field itu mengembalikan thread_fingerprint_mismatch.

Kedaluwarsa, kirim ulang, dan 404

Thread kedaluwarsa 5 menit setelah permintaan terakhirnya, dan API menghapusnya paling lambat 1 jam setelah pemakaian terakhir. Setiap jawaban tersimpan memulai ulang 5 menit itu. Thread tidak memenuhi retensi nol data: percakapan, system prompt, dan tool tetap di memori dalam bentuk terenkripsi dan tidak pernah ditulis ke penyimpanan permanen (halaman Message threads, 4 November 2026).

Tidak ada field jawaban yang memberi tahu apakah API menyimpan sebuah giliran, baik saat create maupun continue. Anda mengetahuinya dari permintaan continue berikutnya, jadi aplikasi Anda tetap menjadi sumber kebenaran dan menyimpan salinan sendiri untuk tiap pesan (halaman Message threads, 4 November 2026).

Saat continue mengembalikan 404 thread_not_found, kirim percakapan lengkap dalam permintaan create baru dan lanjutkan dari id jawaban itu. API memberi 404 yang sama pada semua kasus ini:

• thread sudah kedaluwarsa;
• giliran sebelumnya sudah dilayani lalu dibuang, misalnya panggilan tool yang terpotong max_tokens;
• jawaban sebelumnya ditulis model fallback;
• jawaban sebelumnya masih dibuat;
• permintaan datang dari organisasi, workspace, pengguna, atau kunci workspace lain;
• pesan baru membawa isi yang tidak ada di percakapan tersimpan, misalnya gambar pertama pada percakapan yang belum punya gambar.

Mengirim ulang percakapan lengkap selalu aman dan memperbaiki semua kasus itu.

Streaming menambah satu aturan: lanjutkan dari id jawaban hanya setelah message_stop, karena continue yang dikirim lebih awal bisa mengembalikan 404. Kalau stream permintaan continue terputus sebelum message_stop, kirim permintaan continue yang sama sekali lagi, dan kirim ulang semuanya kalau hasilnya thread_already_continued atau thread_continue_in_flight. Stream yang terputus diserahkan helper SDK kepada Anda.

Tiga kasus lain punya jalannya sendiri:

• pause_turn: lanjutkan dari id jawaban itu dengan "messages": []. Kalau hasilnya 404, kirim ulang semuanya termasuk jawaban yang dijeda.
• stop_reason: "refusal": mulai thread baru tanpa giliran yang menyebabkannya; API mungkin sudah menyimpan giliran yang ditolak.
• entri fallback_message di usage.iterations, atau di message_delta terakhir sebuah stream, menandai jawaban fallback: kirim ulang semuanya.

Error

Kelima error thread kembali sebelum model berjalan: permintaan tidak memakai token dan masa berlaku thread tidak berubah. error.type bernilai invalid_request_error untuk 400 dan not_found_error untuk 404 (halaman Message threads, 4 November 2026).

• 404, thread_not_found: API tidak bisa melanjutkan thread ini. Kirim percakapan lengkap dalam permintaan create baru.
• 400, thread_fingerprint_mismatch: sebuah field tetap berbeda dari nilai yang tersimpan dengan thread. Jaga tetap sama atau mulai thread baru.
• 400, thread_already_continued: id jawaban itu sudah dipakai sekali. Lanjutkan dari id terbaru, dan kirim ulang semuanya kalau Anda tidak pernah menerimanya.
• 400, thread_continue_in_flight: continue lain dari id yang sama masih berjalan, biasanya percobaan Anda sebelumnya. Biarkan selesai atau kirim ulang semuanya.
• 400, thread_unsupported_request: permintaan memakai fitur atau pengaturan organisasi yang tidak didukung thread. error.details.unsupported menyebut salah satu dari context_management, cache_control, fallbacks, hipaa, atau inference_hooks; daftar itu bisa bertambah, jadi kalau ada nilai yang tidak Anda kenali, kirim percakapan lengkap tanpa thread.

Message Batches menolak field thread (item batch yang membawanya gagal dengan invalid_request_error), dan penghitungan token serta pemadatan mengembalikan 400; begitu juga penyuntingan konteks selain clear_thinking_20251015 dengan keep: "all". Organisasi siap HIPAA dan organisasi dengan Inference hooks aktif dikecualikan. Mendaftar, membaca, dan menghapus thread tidak ada di API.

Pertanyaan umum

Apa itu Claude message threads API?

Fitur beta API Messages yang menyimpan percakapan di sisi Anthropic supaya giliran berikutnya hanya mengirim pesan baru. Header beta-nya message-threads-2026-08-12, dan setiap permintaan menambahkan objek thread dengan type bernilai create atau continue.

Apakah thread bekerja dengan cache prompt?

Ya. Thread tidak meng-cache prompt Anda: kirim cache_control tingkat atas di setiap permintaan dan tetap di empat breakpoint. Titik pada pesan tersimpan tidak masuk hitungan; titik tingkat atas dan yang ada di system atau tools masuk.

Bisakah saya mengganti model di tengah thread?

Mengganti model butuh thread baru. model adalah field tetap, jadi nilai berbeda mengembalikan 400 thread_fingerprint_mismatch; mulai thread baru dengan percakapan lengkap dan model baru.

Mengapa continue mengembalikan 400 tanpa error_code?

previous_message_id hilang di continue, atau permintaan itu memuat system atau tools, bahkan sebagai null. 400 seperti ini membawa message dan melewatkan error_code, jadi bacalah teksnya.

Berapa lama thread bertahan, dan apa yang terjadi setelah kedaluwarsa?

Thread kedaluwarsa 5 menit setelah permintaan terakhir dan dihapus paling lambat 1 jam setelah pemakaian terakhir. Setelah itu continue mengembalikan 404 thread_not_found; kirim percakapan lengkap dalam permintaan create baru dan lanjutkan dari id jawabannya.

Sumber yang diperiksa

• Anthropic: message threads
• Anthropic: cache prompt
• Anthropic: harga API Claude
• Anthropic: versi API