Claude Message Threads API rehberi

Claude message threads API, uzun bir konuşmayı bir kez gönderip sonraki her turda yalnızca yeni mesajları göndermenizi sağlar. İlk Messages isteğine "thread": {"type": "create"} ve message-threads-2026-08-12 beta başlığını ekleyin; API konuşmayı bellekte tutar ve sonraki istek daha az veri gönderir (Anthropic'in Message threads sayfası, 4 Kasım 2026).

Tüm modellerde beta. 17 model ID'si kullanabiliyor; aşağıdaki kodun çağırdığı Claude Opus 5.5 de bunlardan biri. Beta başlığı bir thread'in her isteğinde bulunur.

Bir thread ne kazandırır

Thread olmadan her tur tüm dökümü taşır: sistem istemi, araç tanımları, önceki tüm mesajlar ve tüm araç sonuçları. Thread bu konuşmayı Claude'un yanıtıyla birlikte yanıtın id değeri altında saklar; continue isteği yalnızca o andan sonra olanları gönderir (Message threads sayfası, 4 Kasım 2026). Her turda daha az veri gider.

Prompt önbelleği aynı konuşmaya başka bir yönden yardım eder. Önbellek isabeti tekrarlanan girdiyi ucuzlatır: Opus 5.5'te milyon token başına 0,20 USD, yeni girdide 4 USD (Anthropic'in fiyat sayfası, 4 Kasım 2026). İstek yine de bu girdiyi taşır. Thread gönderdiğinizi azaltır; önbellek tekrarlananın fiyatını düşürür. Uzun oturumlarda ikisi birlikte gerekir; bağlam tarafını Claude Code token kullanımını azaltma anlatıyor.

Thread'ler fiyatı da hız sınırlarını da değiştirmez (Message threads sayfası, 4 Kasım 2026). Güncel ücretler fiyatlar sayfasında.

Önbelleği siz eklersiniz. Her istekte üst düzey bir cache_control gönderin; API bunu o isteğin messages listesindeki son önbelleklenebilir bloğa uygular. Dört kesme noktası sınırı tüm platform için geçerli prompt önbelleği kuralıdır ve otomatik önbellek dördün birini kullanır (Anthropic'in prompt önbelleği sayfası, 4 Kasım 2026). Şöyle dağıtın:

1. üst düzey cache_control, thread'in her isteğinde bir nokta;
2. biri system üzerinde, create isteğiyle gönderilir;
3. biri tools üzerinde, yine create ile;
4. biri en yeni mesajda.

Daha önce saklanan mesajlardaki kesme noktaları bu sınıra girmez, çünkü continue isteği yalnızca yeni mesajları gönderir. Gönderilen nokta yerinde kalır. Konuşmayı yeniden gönderirken önceki mesajlardaki noktaları kaldırın ve son blokta bir tane bırakın (Message threads sayfası, 4 Kasım 2026).

İlk turu kurun, sonra devam edin

Üç adım:

1. Anthropic anahtarınızı ANTHROPIC_API_KEY içine koyun.
2. system ve tools kullanıyorsanız onlarla birlikte konuşmanın tamamını gönderin ve "thread": {"type": "create"} ekleyin.
3. Yalnızca son yanıttan bu yana olan mesajları "thread": {"type": "continue", "previous_message_id": "<previous id>"} ile gönderin; system ve tools dışarıda kalsın.

Her istek beta başlığını ve anthropic-version: 2026-10-21 sürümünü taşır; bu, geçerli sürümdür (Anthropic'in sürüm sayfası, 4 Kasım 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"}
  }'

Bu yanıtın id değerini saklayın. Sonraki istek yalnızca yeni mesajı gönderir:

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

Her yanıtın en yeni id değerini tutun: thread yalnızca ekleme kabul eder, her yanıt id değeri bir kez devam ettirilebilir ve sonraki istek en sonuncuyu kullanmalıdır (Message threads sayfası, 4 Kasım 2026).

API anahtarı için başka bir yol gerekiyorsa OmniaKey aynı model ID'leriyle Claude API erişimi satıyor, istek gövdesi değişmiyor. Thread'ler Anthropic tarafında beta; üretimde onlara dayanmadan önce kullandığınız aracının thread alanını değiştirmeden geçirdiğini kontrol edin.

Python SDK id'leri sizin yerinize izler. Yalnızca çağrıyı hazırlayan bir yardımcıyı client.beta.messages.thread(...) ile kurun ve her turu thread.send() ile gönderin. Yardımcı beta başlığını ekler, ilk turda oluşturur, yalnızca yeni mesajlarla devam eder ve continue thread_not_found, thread_already_continued ya da thread_continue_in_flight döndürdüğünde konuşmanın tamamını bir kez yeni bir create isteğiyle yeniden gönderir (Message threads sayfası, 4 Kasım 2026).

import anthropic

client = anthropic.Anthropic()  # ANTHROPIC_API_KEY değerini okur

# Yardımcı henüz bir şey göndermez; her turda yeniden kullanılan alanları tutar.
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)  # bir sonraki sefer bu id'den devam edin

Bu istekleri Anthropic API'sine karşı çalıştırmadık; istek biçimi Anthropic'in Message threads sayfasından geliyor. Akış için thread.stream(...) ve stream.get_final_message() aynı akışı verir; id'yi kendiniz izlemeyi tercih ederseniz thread.previous_message_id değeri döndürür.

Neyi yeniden göndermeli, neyi asla

Sabit alanları her istekte aynı değerlerle gönderin, system ile tools yalnızca create isteğinde olsun, serbest alanlar turdan tura değişebilir.

Değişen sabit alanın 400'ü thread_fingerprint_mismatch taşır ve mesaj farklı alanları listeler. Böyle bir değeri değiştirmek için konuşmanın tamamı ve yeni değerle yeni bir thread başlatın.

previous_message_id yoksa continue 400 döndürür; gövdede message olur ama error_code olmaz. system veya tools eklemek de aynı sonucu verir. Continue tam olarak son yanıttan bu yana olan mesajları taşımalıdır.

mcp_servers sabittir, ama sunucu URL'leri ve yetkilendirme token'ları yalnızca isteğinizde bulunur; MCP kullanan her istekte bu listeyi gönderin, token istekler arasında değişebilir. Container id de yalnızca isteğinizde durur, bu yüzden container her seferinde gönderilir (Message threads sayfası, 4 Kasım 2026).

Sunucu tarafı fallback create anında belirlenir: fallbacks ya thread'in her isteğinde gönderilir ya da hiç gönderilmez. Değer turlar arasında değişebilir, ama alanı eklemek veya çıkarmak thread_fingerprint_mismatch döndürür.

Süre dolumu, yeniden gönderme ve 404

Thread son isteğinden 5 dakika sonra süresi dolar ve API onu son kullanımdan en geç 1 saat sonra siler. Saklanan her yanıt 5 dakikayı yeniden başlatır. Thread'ler sıfır veri saklama için uygun değildir: konuşma, sistem istemi ve araçlar bellekte şifreli durur ve kalıcı depoya hiç yazılmaz (Message threads sayfası, 4 Kasım 2026).

Yanıtta hiçbir alan API'nin bir turu saklayıp saklamadığını söylemez; create için de continue için de böyle. Bunu bir sonraki continue isteğinde öğrenirsiniz, bu yüzden uygulamanız doğruluk kaynağı olarak kalır ve her mesajın kendi kopyasını tutar (Message threads sayfası, 4 Kasım 2026).

Continue 404 thread_not_found döndürdüğünde konuşmanın tamamını yeni bir create isteğiyle gönderin ve o yanıtın id değerinden devam edin. API şu durumların hepsinde aynı 404'ü verir:

• thread'in süresi doldu;
• önceki tur işlendi ve sonra atıldı; örneğin max_tokens ile kesilen bir araç çağrısı;
• önceki yanıtı bir fallback modeli yazdı;
• önceki yanıt hâlâ üretiliyor;
• istek başka bir kuruluştan, çalışma alanından, kullanıcıdan veya çalışma alanı anahtarından geldi;
• yeni mesajlar saklanan konuşmada olmayan içerik ekliyor; örneğin hiç görseli olmayan bir konuşmaya giren ilk görsel.

Konuşmanın tamamını yeniden göndermek her zaman güvenlidir ve bu durumların hepsini onarır.

Akış bir kural daha ekler: yanıtın id değerinden yalnızca message_stop sonrasında devam edin, çünkü daha erken gönderilen continue 404 döndürebilir. Bir continue isteğinin akışı message_stop öncesinde koparsa aynı continue isteğini yeniden gönderin; thread_already_continued veya thread_continue_in_flight dönerse konuşmanın tamamını yeniden gönderin. Kopan akışı SDK yardımcısı size bırakır.

Üç durumun kendi yolu var:

• pause_turn: o yanıtın id değerinden "messages": [] ile devam edin. 404 dönerse duraklatılan yanıtı ekleyerek her şeyi yeniden gönderin.
• stop_reason: "refusal": buna yol açan turu çıkarıp yeni bir thread başlatın; API reddedilen turu zaten tutuyor olabilir.
• usage.iterations içinde ya da bir akışın son message_delta mesajında fallback_message girdisi varsa bu bir fallback yanıtıdır: her şeyi yeniden gönderin.

Hatalar

Beş thread hatası da model çalışmadan döner: istek token harcamaz ve thread'in süresi değişmez. error.type 400'lerde invalid_request_error, 404'te not_found_error olur (Message threads sayfası, 4 Kasım 2026).

• 404, thread_not_found: API bu thread'i sürdüremiyor. Konuşmanın tamamını yeni bir create isteğiyle gönderin.
• 400, thread_fingerprint_mismatch: sabit bir alan thread ile saklanan değerden farklı. Aynı tutun ya da yeni bir thread başlatın.
• 400, thread_already_continued: bu yanıt id değeri bir kez kullanıldı. En yeni id değerinden devam edin; hiç almadıysanız her şeyi yeniden gönderin.
• 400, thread_continue_in_flight: aynı id üzerinden başka bir continue hâlâ çalışıyor; genelde kendi önceki denemenizdir. Bitmesini bekleyin ya da her şeyi yeniden gönderin.
• 400, thread_unsupported_request: istek, thread'lerin desteklemediği bir özellik ya da kuruluş ayarı kullanıyor. error.details.unsupported değeri context_management, cache_control, fallbacks, hipaa veya inference_hooks içinden birini söyler; liste büyüyebilir, bu yüzden tanımadığınız bir değerde konuşmanın tamamını thread olmadan gönderin.

Message Batches thread alanını reddeder (bu alanı taşıyan parti öğesi invalid_request_error ile başarısız olur); token sayımı ve sıkıştırma 400 döndürür; clear_thinking_20251015 ve keep: "all" dışındaki bağlam düzenlemesi de 400 döndürür. HIPAA'ya hazır kuruluşlar ve Inference hooks açık kuruluşlar da kapsam dışıdır. Thread listeleme, okuma ve silme API'de yok.

Sık sorulan sorular

Claude message threads API nedir?

Konuşmayı Anthropic tarafında saklayıp sonraki turların yalnızca yeni mesajları göndermesini sağlayan bir Messages API beta özelliğidir. Beta başlığı message-threads-2026-08-12 ve her istek type değeri create veya continue olan bir thread nesnesi ekler.

Thread'ler prompt önbelleğiyle çalışır mı?

Evet. Thread isteminizi sizin yerinize önbelleklemez: her istekte üst düzey cache_control gönderin ve dört kesme noktasında kalın. Saklanan mesajlardaki noktalar bu sayıya girmez; üst düzeydeki ve system ile tools üzerindekiler girer.

Thread'in ortasında modeli değiştirebilir miyim?

Model değişikliği yeni bir thread ister. model sabit bir alandır, farklı değer 400 thread_fingerprint_mismatch döndürür; konuşmanın tamamı ve yeni modelle yeni bir thread başlatın.

Continue neden error_code olmadan 400 döndürür?

Continue'da previous_message_id yoktur ya da system veya tools vardır; null olsa bile. Bu 400'ler message taşır ve error_code atlar, bu yüzden metni okuyun.

Thread ne kadar sürer ve süresi dolunca ne olur?

Son istekten 5 dakika sonra süresi dolar ve son kullanımdan en geç 1 saat sonra silinir. Sonrasında continue 404 thread_not_found döndürür; konuşmanın tamamını yeni bir create isteğiyle gönderin ve onun id değerinden devam edin.

Kontrol edilen kaynaklar

• Anthropic: message threads
• Anthropic: prompt önbelleği
• Anthropic: Claude API fiyatları
• Anthropic: API sürümleri