# Claude Message Threads API: panduan thread

> Thread pesan di API Claude: header beta, permintaan create dan continue, field yang harus dikirim ulang, masa berlaku, dan langkah setelah 404.

- Canonical HTML: https://omniakey.com/id/blog/claude-message-threads-api-guide
- Markdown: https://omniakey.com/id/blog/claude-message-threads-api-guide.md
- Published: 2026-11-04 (updated 2026-11-04)
- Author: Kiki, COO at OmniaKey
- Language: id
- Category: API setup
- Reading time: 9 min
- All posts: https://omniakey.com/blog/llms.txt

---

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](https://omniakey.com/id/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](https://omniakey.com/id/blog/reduce-claude-code-token-usage) membahas sisi konteks.

Thread tidak mengubah harga maupun batas laju (halaman Message threads, 4 November 2026). Tarif terkini ada di halaman [harga](https://omniakey.com/id/pricing).

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).

```bash
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:

```bash
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).

```python
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.

|Grup|Field|Aturan|
|-|-|-|
|Hanya create|`system`, `tools`|Hanya di permintaan create; mengirim salah satunya di permintaan continue, bahkan sebagai `null`, menghasilkan 400.|
|Tetap|`model`, `tool_choice`, `thinking`, `mcp_servers` kecuali token otorisasi tiap server, `context_management`, `output_config`, `skills` di `container`, `cache_control` tingkat atas, dan himpunan nilai `anthropic-beta`|Nilai sama setiap kali. Nilai berbeda menghasilkan 400 dan menyebut field yang berbeda.|
|Bebas|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier`, dan field tanpa nama|Ubah kapan saja.|

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](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: cache prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: harga API Claude](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: versi API](https://platform.claude.com/docs/en/api/versioning)