Thread pesan

Dengan “message thread” (thread pesan), permintaan menjadi lebih kecil, dan “time to first token” (waktu hingga token pertama) tetap lebih rendah dan lebih stabil seiring bertambahnya percakapan. Thread paling membantu dalam loop agen yang panjang. Tanpa thread, setiap giliran mengunggah ulang seluruh percakapan, dan API memvalidasi serta melakukan tokenisasi ulang terhadap semuanya. Dengan thread, sebagian besar pekerjaan tersebut hanya mencakup giliran baru.

“Message thread” (thread pesan) menyimpan percakapan di server untuk waktu yang singkat. Anda mengirimkan percakapan lengkap satu kali, beserta prompt sistem dan alat Anda. Pada setiap giliran berikutnya, Anda hanya mengirimkan pesan-pesan baru dan id dari respons sebelumnya. API membangun ulang percakapan sebelum memanggil model. Anda menambahkan satu parameter, thread, ke permintaan Messages API. Responsnya adalah pesan seperti biasa.

Cara kerja thread pesan

• Buat. Kirim permintaan pertama Anda seperti yang Anda lakukan saat ini, dengan percakapan lengkap, system, dan tools, lalu tambahkan "thread": {"type": "create"}. API menyimpan percakapan, termasuk balasan Claude, di bawah id respons.
• Lanjutkan. Kirim hanya pesan-pesan sejak respons sebelumnya, lalu tambahkan "thread": {"type": "continue", "previous_message_id": "<previous id>"}. Jangan sertakan system dan tools dalam permintaan. Thread mempertahankan nilai-nilai dari permintaan create. Gunakan setiap id respons baru untuk giliran berikutnya.
• Putar ulang. Thread bersifat best-effort. Thread kedaluwarsa 5 menit setelah permintaan terakhirnya, dan API menghapusnya paling lambat 1 jam setelah penggunaan terakhirnya. Setiap respons yang disimpan API memulai ulang waktu 5 menit tersebut. Jika API tidak lagi dapat melanjutkan thread, permintaan continue akan mengembalikan error 404. Kirim kembali percakapan lengkap dalam permintaan create baru, dan lanjutkan dari id respons tersebut. Helper thread SDK melakukan pemutaran ulang ini untuk Anda (lihat Cara kerja helper SDK). Setelah respons dari model fallback, lihat Menggunakan fallback dengan thread.

Aplikasi Anda tetap menjadi sumber kebenaran untuk percakapan. Simpan salinan Anda sendiri dari setiap pesan, dan bangun jalur pemutaran ulang sejak awal. Tidak ada respons, baik untuk permintaan create maupun continue, yang menyatakan apakah API menyimpan giliran tersebut. Anda baru mengetahuinya pada permintaan continue berikutnya. Helper thread SDK menyimpan salinan ini di memori selama objek helper tersebut ada, dan tidak menyimpannya di tempat lain. Jika percakapan harus bertahan lebih lama dari proses Anda, simpan salinan Anda sendiri.

Menggunakan thread dengan SDK

SDK memiliki helper thread yang membangun permintaan thread untuk Anda. Buat helper tersebut dengan field yang sama seperti permintaan Messages, lalu kirimkan satu giliran pada satu waktu. Helper menyimpan percakapan lengkap di memori.

Contoh ini memiliki dua giliran. Helper membuat thread pada giliran pertama dan melanjutkannya pada giliran kedua, serta menambahkan beta header untuk Anda. cache_control tingkat atas bersifat opsional. Field ini meminta caching prompt pada setiap giliran (lihat Caching prompt pada thread). Tanpanya, setiap giliran berikutnya tetap hanya mengirimkan pesan-pesan baru, tetapi tidak ada yang di-cache kecuali Anda menambahkan cache breakpoint sendiri.

client = anthropic.Anthropic()

# Buat helper. Panggilan ini tidak mengirim permintaan apa pun.
thread = client.beta.messages.thread(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
)

# Giliran 1: helper membuat thread dan mengirim seluruh percakapan
thread.send({"role": "user", "content": "Hi! I have a question about an order."})

# Giliran 2: helper melanjutkan thread dan hanya mengirim pesan baru
second = thread.send(
    {"role": "user", "content": "How long does standard shipping usually take?"}
)

for block in second.content:
    if block.type == "text":
        print(block.text)

Mengirim field thread sendiri

Untuk membangun permintaan thread sendiri, misalnya dengan cURL, CLI, atau metode create biasa dari SDK, tambahkan field thread ke setiap permintaan.

Kirim beta header message-threads-2026-08-12 pada setiap permintaan dalam sebuah thread.

Contoh ini membuat thread pada giliran pertama dan melanjutkannya pada giliran kedua. cache_control tingkat atas meminta caching prompt pada setiap giliran. Field ini berlaku setelah percakapan lebih panjang dari panjang minimum yang dapat di-cache.

client = anthropic.Anthropic()

# Giliran 1: kirim seluruh percakapan dan buat thread
first = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system="You are a support agent for Acme. Keep replies short.",
    messages=[{"role": "user", "content": "Hi! I have a question about an order."}],
    thread={"type": "create"},
    betas=["message-threads-2026-08-12"],
)

# Giliran 2: kirim hanya pesan baru dan id respons giliran 1.
# Hilangkan system dan tools: thread sudah menyimpannya.
second = client.beta.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    messages=[
        {"role": "user", "content": "How long does standard shipping usually take?"}
    ],
    thread={"type": "continue", "previous_message_id": first.id},
    betas=["message-threads-2026-08-12"],
)

for block in second.content:
    if block.type == "text":
        print(block.text)

Apa yang dikirim pada setiap permintaan

API tidak menyimpan URL server MCP, token otorisasi MCP, atau id container. Kirim mcp_servers dan container pada setiap permintaan yang menggunakannya. Token otorisasi MCP dapat berubah antar permintaan.

Helper thread SDK tidak menyertakan system dan tools dalam permintaan continue untuk Anda dan mengirim ulang field-field tetap pada setiap giliran.

Jika Anda menggunakan fallback sisi server, kirim field fallbacks pada setiap permintaan dalam thread atau tidak sama sekali. Lihat Menggunakan fallback dengan thread.

Untuk mengubah field khusus create atau field tetap, mulai thread baru: kirim percakapan lengkap dalam permintaan create dengan nilai-nilai baru.

Pada Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, dan Claude Haiku 5.5, mengubah system atau tools membuat blok thinking dan redacted_thinking yang sudah ada dalam percakapan menjadi tidak valid, dan permintaan create dapat mengembalikan error 400. Untuk menghindarinya, keluarkan semua blok thinking dan redacted_thinking dari percakapan yang Anda kirim. Model kemudian menjawab tanpa penalaran sebelumnya tersebut. Lihat Apa yang dihitung sebagai edit, Ketika prefix_mismatch_behavior tidak diatur, dan Apa yang dilakukan API terhadap blok yang tidak valid.

Kirim hanya pesan-pesan baru pada permintaan continue. API tidak memeriksanya terhadap pesan-pesan yang sudah dimilikinya. Pesan yang Anda kirim ulang dapat muncul dua kali dalam percakapan, atau permintaan dapat mengembalikan error. Misalnya, permintaan continue yang dimulai dengan respons sebelumnya akan mengembalikan error.

Pesan-pesan baru biasanya dimulai dengan pesan user: giliran pengguna Anda berikutnya, atau blok tool_result yang menjawab tool_use dalam respons sebelumnya. Jika respons berhenti dengan stop_reason: "pause_turn", lanjutkan dengan permintaan continue dari id respons tersebut dan daftar messages kosong ("messages": []). Jika permintaan tersebut mengembalikan error 404, putar ulang percakapan lengkap, termasuk respons yang dijeda, dalam permintaan create baru. Jangan mengirim pesan user baru saat giliran sedang dijeda: API akan menolaknya. Dengan helper thread SDK, panggil send() tanpa pesan: helper mengirim permintaan ini dan melakukan pemutaran ulang jika terjadi error 404.

Thread bersifat “append-only” (hanya dapat ditambahkan), dan setiap id respons hanya dapat dilanjutkan satu kali. Selalu lanjutkan dari id respons terbaru dalam thread. Untuk mengedit atau membuat cabang dari pesan sebelumnya, mulai thread baru dengan permintaan create. Untuk mengganti giliran-giliran sebelumnya dengan ringkasan, lihat Memadatkan percakapan.

Caching prompt pada thread

Thread tidak melakukan cache prompt Anda untuk Anda. “Prompt caching” (caching prompt) bekerja sama seperti tanpa thread: Anda memilih di mana cache breakpoint ditempatkan.

Untuk melakukan cache setiap giliran, kirim cache_control tingkat atas pada setiap permintaan dalam thread, seperti pada contoh sebelumnya. API menerapkannya ke blok terakhir dari messages setiap permintaan yang dapat di-cache. Setiap giliran kemudian membaca percakapan sebelumnya dari cache dan menulis giliran baru ke dalamnya. cache_control tingkat atas adalah field tetap: kirim nilai yang sama pada setiap permintaan.

Anda juga dapat menempatkan breakpoint cache_control pada blok sendiri:

• Breakpoint yang Anda kirim pada permintaan create tetap berfungsi pada setiap giliran berikutnya jika berada di tools, di system, atau di blok pesan sebelum blok terakhir. Breakpoint pada blok terakhir dari messages sebuah permintaan menulis cache pada permintaan tersebut. Untuk melakukan cache pada setiap giliran baru, kirim breakpoint pada setiap permintaan. Permintaan tanpa breakpoint mungkin masih membaca sebagian percakapan dari cache.
• Anda tidak dapat memindahkan atau menghapus breakpoint setelah Anda mengirimnya, karena permintaan continue tidak dapat mengirim ulang pesan sebelumnya.
• Permintaan dengan thread dapat membawa paling banyak 4 breakpoint cache_control. cache_control tingkat atas dihitung sebagai satu. Breakpoint pada system dan tools dari permintaan create dihitung lagi pada setiap permintaan continue. Breakpoint pada pesan tersimpan sebelumnya tidak dihitung. Kelebihan satu breakpoint saja akan mengembalikan error 400 dengan kode thread_unsupported_request.
• Jika Anda menempatkan breakpoint pada blok pesan sendiri, hapus breakpoint tersebut dari pesan-pesan sebelumnya saat Anda memutar ulang percakapan dalam permintaan create baru, dan pertahankan satu pada blok terakhir, sehingga permintaan tetap berada dalam batas 4.

Streaming

Thread berfungsi dengan streaming. id respons tiba dalam event message_start, tetapi lanjutkan darinya hanya setelah Anda menerima event message_stop. Permintaan continue yang dikirim lebih awal dapat mengembalikan error 404.

Jika stream dari permintaan continue terputus sebelum message_stop, kirim ulang permintaan continue yang sama. Jika permintaan tersebut mengembalikan error thread_already_continued atau thread_continue_in_flight, lakukan replay percakapan lengkap dalam permintaan create baru.

Koneksi Anda mungkin terputus saat server masih menghasilkan respons, atau setelah server menyimpannya. Itulah sebabnya API dapat menolak percobaan ulang. Melakukan replay selalu aman.

Helper thread SDK tidak mencoba ulang permintaan continue setelah stream terputus. Lihat Cara kerja helper SDK.

Memulihkan ketika thread tidak dapat dilanjutkan

Permintaan continue mengembalikan error 404 dengan error.details.error_code diatur ke thread_not_found ketika API tidak dapat melanjutkan thread. Respons tidak menyebutkan alasannya. Penyebabnya meliputi hal-hal berikut:

• Thread telah kedaluwarsa.
• API melayani giliran sebelumnya tetapi tidak menyimpannya. Misalnya, API tidak menyimpan respons yang berakhir dengan pemanggilan alat yang terpotong oleh max_tokens.
• Respons sebelumnya ditulis oleh model fallback. Lihat Menggunakan fallback dengan thread.
• Respons sebelumnya masih dalam proses pembuatan.
• Permintaan berasal dari organisasi atau workspace yang berbeda.
• Permintaan berasal dari pengguna atau akun layanan yang berbeda dari yang membuat thread. Thread yang dibuat dengan kunci workspace (legacy) tetap terikat pada kunci tersebut, jadi gunakan kunci yang sama untuk seluruh thread.
• Pesan-pesan baru menambahkan sesuatu yang tidak dapat diterima oleh percakapan yang tersimpan. Misalnya, gambar pertama dalam percakapan yang sebelumnya tidak memiliki gambar dapat mengembalikan error ini.

Untuk memulihkan, kirim seluruh percakapan dari salinan Anda sendiri dalam permintaan create baru, dengan system dan tools. Helper thread SDK mengirimkan permintaan create ini satu kali dengan sendirinya, dan tidak menyertakan breakpoint cache_control dari giliran sebelumnya saat melakukannya. Jika pesan-pesan sebelumnya dalam salinan Anda membawa breakpoint cache_control, hapus terlebih dahulu (lihat Caching prompt pada thread). Kemudian lanjutkan dari id respons yang baru. Jika model fallback yang menulis respons sebelumnya, lihat Menggunakan fallback dengan thread. Untuk menyingkirkan penyebab terkait kepemilikan, gunakan kunci API dan workspace yang sama untuk setiap permintaan dalam sebuah thread. Di Claude Platform on AWS, tandatangani setiap permintaan dalam sebuah thread dengan kredensial untuk IAM role atau IAM user yang membuatnya.

Permintaan untuk model yang tidak ada juga mengembalikan error 404, jadi periksa error.details.error_code sebelum Anda melakukan replay.

Jika permintaan continue masih mengembalikan error 404 tepat setelah Anda memutar ulang, API mungkin tidak dapat menyimpan percakapan tersebut, misalnya percakapan yang sangat besar. Kirim tanpa thread. Helper thread SDK melakukan ini ketika Anda membuatnya dengan unsupported_request_behavior diatur ke continue_unthreaded. Jika tidak, helper memutar ulang pada setiap giliran.

Setelah penolakan

Ketika respons memiliki stop_reason: "refusal", jangan lanjutkan thread. API mungkin sudah menyimpan giliran yang ditolak, dan permintaan continue tidak dapat menghapusnya. Mulai thread baru dengan permintaan create yang tidak menyertakan atau merumuskan ulang giliran yang menyebabkan penolakan. Lihat Penolakan dan fallback. Helper thread SDK melakukan ini untuk Anda: helper tidak menyimpan giliran yang ditolak, dan giliran berikutnya memulai thread baru.

Menggunakan fallback dengan thread

Fallback sisi server tersedia dengan thread di Claude API. Tentukan saat Anda membuat thread: kirim fallbacks pada setiap permintaan dalam thread, atau tidak sama sekali. Nilai fallbacks dapat berubah antar permintaan. Permintaan continue yang menambahkan atau menghapus fallbacks mengembalikan error 400 dengan kode thread_fingerprint_mismatch.

Thread mempertahankan satu model, sehingga API tidak menyimpan giliran yang ditulis oleh model fallback. Anda menerima respons seperti biasa, tetapi Anda tidak dapat melanjutkan dari id-nya. Setelah setiap respons, ikuti langkah-langkah berikut:

1. Jika stop_reason adalah "refusal", ikuti Setelah penolakan.
2. Jika tidak, cari entri fallback_message di usage.iterations. Pada stream, baca entri tersebut dari event message_delta terakhir. Jika tidak ada, lanjutkan thread seperti biasa.
3. Jika ada, model fallback yang menulis respons tersebut. Kirim seluruh percakapan, termasuk respons tersebut dan pesan Anda berikutnya, dalam permintaan create baru. Pertahankan beta header server-side-fallback-2026-07-01 pada permintaan tersebut. Pilih salah satu dari dua permintaan berikut:
   • Permintaan yang sama lagi. Pertahankan model, fallbacks, dan parameter Anda lainnya seperti semula. Jika model yang Anda minta menjawab, API menyimpan thread baru tersebut. Jika model fallback menjawab, respons kembali memiliki entri fallback_message dan API tidak menyimpannya, jadi ulangi langkah ini pada giliran berikutnya. Sticky routing mungkin mengirim permintaan ini langsung ke model fallback, sehingga setiap giliran mungkin mengirim seluruh percakapan. Helper thread SDK bekerja dengan cara ini.
   • Thread baru pada model fallback. Atur model ke model dalam entri fallback_message tersebut, jangan sertakan fallbacks, dan gunakan parameter yang diterima oleh model ini. API langsung menyimpan thread ini, dan thread tetap berada pada model fallback. Percobaan fallback mungkin berjalan dengan pengaturan yang berbeda dari yang Anda kirimkan, sehingga API mungkin menolak nilai yang disalin dari permintaan pertama Anda.
4. Kembali ke langkah 1 dengan respons dari permintaan tersebut. Ketika respons tidak memiliki entri fallback_message, lanjutkan thread baru dari id-nya.

Sticky routing dimulai setelah sebuah permintaan beralih ke fallback (permintaan create, atau permintaan tanpa thread). Selama sekitar satu jam, fitur ini mungkin mengirim permintaan create berikutnya untuk percakapan yang sama yang menyertakan fallbacks langsung ke model fallback, tanpa mencoba model yang Anda minta. API tidak menyimpan satu pun dari giliran tersebut, dan setiap giliran yang dijawab memulai ulang hitungan satu jam tersebut. Permintaan continue tidak pernah memulai routing ini dan tidak pernah menggunakannya. Sticky routing tidak berlaku jika organisasi atau workspace Anda menggunakan zero data retention atau kunci enkripsi yang dikelola pelanggan.

Memadatkan percakapan

Thread bersifat append-only, sehingga Anda tidak dapat mengganti giliran-giliran sebelumnya dengan ringkasan. Untuk memadatkan percakapan, mulai thread baru dari ringkasan tersebut. Tulis ringkasan dalam kode Anda, lalu kirimkan sebagai pesan biasa dalam permintaan create baru, dengan system dan tools. Compaction sesuai permintaan tidak tersedia dengan thread (lihat Fitur yang tidak didukung oleh thread).

Cara kerja helper SDK

Yang dilakukan helper untuk Anda:

• Menambahkan header beta message-threads-2026-08-12 ke setiap permintaan yang menggunakan thread.
• Membuat thread pada giliran pertama dan melanjutkannya setelah itu, dengan hanya mengirim pesan baru dan tidak menyertakan system dan tools.
• Memutar ulang seluruh percakapan satu kali dalam permintaan create baru ketika permintaan continue mengembalikan thread_not_found, thread_already_continued, atau thread_continue_in_flight.
• Melanjutkan respons pause_turn ketika Anda memanggil send() tanpa pesan.
• Memulai thread baru setelah penolakan. Anda mendapatkan respons stop_reason: "refusal" seperti biasa, tetapi helper tidak menyimpan giliran tersebut: helper menarik kembali pesan yang Anda berikan pada panggilan itu. Pesan yang Anda tambahkan dengan thread.append(...), atau yang Anda berikan saat membuat helper, tetap berada dalam antrean. Giliran Anda berikutnya mengirimkannya bersama percakapan dari sebelum giliran yang ditolak, dalam permintaan create baru. Kirim pesan yang dirumuskan ulang, atau, jika pesan dalam antrean yang menyebabkan penolakan, mulai thread baru dari params tanpa pesan tersebut.
• Mengirim permintaan create baru setelah respons dari model fallback. Ketika respons memiliki entri fallback_message di usage.iterations, helper menyimpan respons tersebut dan mengirimkan seluruh percakapan dalam permintaan create baru pada giliran berikutnya. Helper tidak menunggu error 404. Permintaan tersebut mempertahankan model dan fallbacks yang Anda tetapkan.
• Tidak menyertakan breakpoint cache_control dari giliran sebelumnya setiap kali helper mengirimkannya lagi, misalnya dalam pemutaran ulang atau pada giliran pertama dari sebuah fork. Pesan terbaru Anda, system, tools, dan cache_control tingkat atas dikirim sebagaimana Anda memberikannya.

Yang Anda tangani sendiri:

• Fallback. Selama API terus menjawab dari model fallback, helper mengirimkan seluruh percakapan dalam permintaan create baru pada setiap giliran, karena API tidak menyimpan satu pun dari giliran tersebut. Helper kembali ke permintaan continue setelah respons dari model yang Anda minta. Untuk memindahkan percakapan ke model fallback, mulai thread baru dari params dengan model tersebut dan tanpa fallbacks, seperti dalam Menggunakan fallback dengan thread.
• Stream yang terputus. Jika stream berakhir di tengah respons, helper menyimpan blok yang sudah selesai dan teks apa pun yang sudah diterima, dan giliran berikutnya mengirim seluruh percakapan dalam permintaan create baru. Helper tidak mencoba ulang dengan sendirinya: untuk mengirim ulang giliran yang terputus, panggil send() tanpa pesan. Jika bagian yang disimpan berakhir dengan pemanggilan alat, jawab pemanggilan tersebut dalam pesan Anda berikutnya. Jika Anda berhenti membaca stream setelah stream menampilkan stop_reason: "refusal", helper memperlakukan giliran tersebut sebagai penolakan.
• Error lainnya. Error thread_fingerprint_mismatch dan thread_unsupported_request diteruskan ke kode Anda. Untuk melanjutkan tanpa thread setelah error thread_unsupported_request, buat helper dengan unsupported_request_behavior diatur ke continue_unthreaded. Dengan pengaturan tersebut, helper juga berhenti menggunakan thread ketika permintaan continue pertama setelah pemutaran ulang kembali mengembalikan thread_not_found. API mungkin tidak dapat menyimpan percakapan tersebut. Tanpa pengaturan tersebut, helper memutar ulang pada setiap giliran. Tool runner yang membuat thread-nya sendiri menggunakan pengaturan tersebut secara default.

Beta tool runner SDK juga menggunakan thread secara default, yang dapat Anda nonaktifkan saat membuat runner.

Metode helper lainnya

Streaming. Helper mencatat respons ketika stream mencapai message_stop, jadi baca stream hingga akhir. Jika Anda berhenti membaca lebih awal, akhiri stream agar thread bebas untuk giliran berikutnya:

• Python: keluar dari blok with.
• TypeScript: keluar dari loop atau panggil abort().
• Go: panggil Close.
• Java dan Ruby: panggil close().
• C#: lakukan dispose pada enumerator. Keluar dari await foreach melakukan hal ini.
• PHP: panggil close().

Di C#, permintaan dikirim ketika Anda mulai membaca stream.

Di C#, Go, Java, dan PHP, setelah penolakan thread.LastMessage tetap mengembalikan respons giliran sebelumnya, atau tidak mengembalikan apa pun pada giliran pertama. Baca penolakan dari event stream.

Mengubah field. Update tidak mengirimkan apa pun dan berlaku untuk setiap giliran berikutnya. Setelah thread memiliki respons, helper menolak giliran yang mengubah system atau tools, dan API menolak perubahan pada field tetap lainnya (lihat Apa yang dikirim pada setiap permintaan). Untuk mengubah salah satu field ini, mulai thread baru dari params, atau lakukan fork pada thread dan update fork tersebut sebelum giliran pertamanya.

Forking. Fork menyalin percakapan, field, dan opsi permintaan, serta tidak mengirimkan apa pun. Giliran pertamanya mengirimkan percakapan lengkap dalam permintaan create baru, dan kedua thread tersebut independen setelahnya. Fork selalu dimulai dari seluruh percakapan, bukan dari respons sebelumnya.

Params. Params menyimpan field milik helper dan seluruh percakapan. Teruskan params tersebut ke metode yang membuat helper untuk memulai thread baru, misalnya dengan system yang berbeda (lihat Apa yang dikirim pada setiap permintaan), atau dengan messages yang dipangkas untuk membuang giliran-giliran berikutnya. Thread yang Anda mulai dari params mengirim setiap pesan persis seperti yang Anda berikan, termasuk breakpoint cache_control, jadi tetaplah dalam batas 4 (lihat Caching prompt pada thread). Kecuali di Ruby, params tidak menyertakan opsi permintaan, jadi teruskan opsi tersebut lagi.

Output terstruktur. Berikan format output saat Anda membuat helper. Giliran berikutnya tidak dapat mengubahnya. Cara Anda mendapatkan hasil yang telah di-parse bergantung pada SDK:

• Python dan TypeScript: panggil thread.parse(...).
• C#: buat helper dengan client.Beta.Messages.Thread<T>(...).
• Go: Send melakukan unmarshal ke struct yang ditunjuk oleh Params.OutputConfig.Format.Schema.
• Java: buat helper dengan thread(...) dan outputConfig(MyClass.class).
• PHP: send() mengatur parsed pada blok teks ketika outputConfig menyebutkan kelas model.
• Ruby: teruskan output_config: {format: MyModel} ke thread(...), lalu baca reply.parsed_output.

Error

API mengembalikan error dalam tabel ini sebelum model berjalan. Permintaan tidak menggunakan token, dan thread serta waktu kedaluwarsanya tidak berubah. error.type adalah invalid_request_error untuk error 400 dan not_found_error untuk error 404.

Beberapa error 400 untuk permintaan thread tidak membawa error_code, misalnya permintaan continue tanpa previous_message_id, atau permintaan yang menyertakan system atau tools.

Contoh berikut menunjukkan body error:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "thread: a maximum of 4 blocks with cache_control may be provided when `thread` is set. Found 5.",
    "details": {
      "error_code": "thread_unsupported_request",
      "unsupported": ["cache_control"]
    }
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

Fitur yang tidak didukung oleh thread

Thread tidak mendukung fitur-fitur berikut:

• Message Batches. Item permintaan yang menyertakan thread berakhir dengan invalid_request_error dalam hasil batch.
• Penghitungan token. Permintaan penghitungan token yang menyertakan thread mengembalikan error 400. Sebagai gantinya, hitung percakapan lengkap, dengan system dan tools.
• Compaction. Compaction sesuai permintaan tidak tersedia dengan thread. Permintaan yang menyertakan thread mengembalikan error 400 jika permintaan tersebut mengatur parameter compaction, atau jika mengirimkan blok compaction dengan beta header compact-2026-09-04. Lihat Memadatkan percakapan.
• Context editing, kecuali clear_thinking_20251015 dengan keep: "all".
• Organisasi yang mengaktifkan kesiapan HIPAA.
• Organisasi yang mengaktifkan Inference hooks.

API menolak sebagian besar permintaan yang tidak didukung oleh thread dengan error 400 dan kode thread_unsupported_request. Jika error.details.unsupported ada, field tersebut berisi salah satu nilai berikut:

API dapat menambahkan nilai ke daftar ini. Jika Anda mendapatkan nilai yang tidak Anda kenali, kirim percakapan lengkap tanpa thread. Permintaan yang memenuhi beberapa kondisi ini mendapatkan error yang hanya menyebutkan salah satunya.

Keterbatasan

• Tidak ada API untuk mencantumkan, membaca, atau menghapus thread.
• Thread tersedia di Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), dan Claude in Microsoft Foundry.

Harga dan batas laju

Thread tidak mengubah harga atau “rate limits” (batas laju).

Retensi data

Thread pesan tidak memenuhi syarat ZDR. Menggunakan fitur ini tidak memengaruhi penggunaan Anda atas fitur lain yang memenuhi syarat ZDR. API menampung thread di memori, dienkripsi dengan kunci yang dikelola server, tidak pernah menuliskannya ke penyimpanan permanen, dan menghapusnya paling lambat 1 jam setelah penggunaan terakhirnya.

Thread menampung percakapan yang dikirim API ke model, system dan tools dari permintaan create, serta fingerprint dari field tetap, yang digunakan untuk memeriksa permintaan berikutnya. Thread menampung file berdasarkan referensi, jadi pastikan setiap file yang digunakan percakapan tetap tersedia selama Anda menggunakan thread.

Untuk kelayakan ZDR di semua fitur, lihat API dan retensi data.

Lihat juga

• Caching prompt
• Streaming
• Error

Ketersediaan

Thread pesan dalam versi beta di semua model.

Dukungan API

Header beta memungkinkan Anda mengakses fitur eksperimental dan kemampuan model baru sebelum menjadi bagian dari API standar.