Claude Message Threads API Rehberi (Kasım 2026)

Anthropic, message threads özelliğini 2 Kasım 2026'da herkese açık beta olarak kullanıma açtı. Ancak başlıktaki avantaj kolayca yanlış anlaşılabilir: 500K-1M token'lık isteklerde medyan ilk token süresi yaklaşık %35 azalıyor, fakat token faturanız değişmiyor. Uzun ajan döngüleri çalıştırıyorsanız bu özellik, 5 dakikalık katı boşta kalma sınırı olan bir aktarım optimizasyonu.

Daha hızlı istek, aynı fatura: Threads neyi değiştiriyor?

Message threads, Messages API için sunucu tarafında tutulan geçici konuşma durumudur ve 2 Kasım 2026'da herkese açık beta olarak kullanıma sunuldu. İlk istekte thread: { "type": "create" } ile tüm geçmişi gönderiyorsunuz. Sonraki isteklerde ise yalnızca yeni mesajları ve previous_message_id değerini, thread: { "type": "continue" } ile iletiyorsunuz. Anthropic'in duyurusuna ve platform dokümantasyonuna göre durum şifreli bellekte tutuluyor, diske hiç yazılmıyor, 5 dakika boşta kaldıktan sonra süresi doluyor ve son kullanımdan en geç 1 saat sonra siliniyor.

Thread içindeki her istekte anthropic-beta: message-threads-2026-08-12 beta başlığını göndermeniz gerekiyor. Fiyatlandırma ve hız limitleri değişmiyor: Claude her turda konuşmanın tamamını okumaya devam ettiği için daha az veri yüklemenize rağmen aynı girdi ve çıktı token ücretini ödüyorsunuz.

"Evet, güzel ama token maliyetini azaltmıyor :( Claude her turda konuşmanın tamamını okumaya devam ediyor ve token tüketimi değişmiyor" — Resmî duyuru zincirine yanıt veren @_navicstein

Resmî duyuruya göre 500K-1M token'lık isteklerde medyan TTFT yaklaşık %35 daha düşük; ancak token indirimi yok.

Threads ile prompt caching arasındaki fark

Threads, gönderdiğiniz veriyi azaltır; prompt caching ise tam fiyat ödediğiniz veriyi azaltır. Threads herhangi bir şeyi otomatik olarak önbelleğe almaz; cache_control kesme noktalarını yine sizin tanımlamanız gerekir. Aşağıdaki ayrıntılı etkileşim açıklaması, uygulama analizine dayanıyor: Her devam isteğinde üst düzey bir cache_control kullanın. Önbellek okumaları temel girdi fiyatının 0,1 katı; Claude Opus 5.5 ve Sonnet 5.5'te ise 0,05 katı üzerinden ücretleniyor.

Threads ile yönetilen ajan oturumu thread'lerini karıştırmayın

Arama sonuçlarında iki farklı "thread" türü sık sık birbirine karışıyor. Bu yazıdaki Messages API message threads, istek boyutunu küçültmeye yarayan ve geçici olarak tutulan bir yapı; listeleme, okuma veya silme API'si bulunmuyor. Managed-agent session threads (GET /v1/sessions/{session_id}/threads/{thread_id}) ise Anthropic'in managed-agents API'si içindeki yürütme thread'leri ve bunlar için listeleme, alma ve arşivleme uç noktaları mevcut. Dokümanda child threads, event streams veya archiving ifadelerini görüyorsanız yanlış API'ye bakıyorsunuz. İhtiyacınız olan yüzeyi doğrulamak için session threads API referansına göz atın.

Bir thread'in yaşam döngüsü: oluşturma, devam ettirme ve süre dolumu

Pratikte thread yalnızca sona ekleme mantığıyla çalışıyor: tüm bağlamla oluşturuluyor, devam isteklerinde yalnızca değişiklikler gönderiliyor, kaybolduğunda ise geçmiş yeniden oynatılıyor. Dallanma, düzenleme, geri sarma veya inceleme API'si yok. Her yanıt yeni bir id döndürüyor ve her id yalnızca bir kez devam ettirilebiliyor. Bu bölümdeki alan ve hata kuralları, platform dokümantasyonuna ve uygulama analizine dayanıyor.

Create isteği her şeyi taşır: tam messages, system ve tools alanlarının yanı sıra:

{
  "model": "claude-opus-5-5",
  "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" }
}

Continue isteği yalnızca yeni içeriği taşır; bu genellikle bir kullanıcı mesajı veya tool_result bloklarıdır:

{
  "model": "claude-opus-5-5",
  "messages": [{ "role": "user", "content": "How long does standard shipping usually take?" }],
  "thread": { "type": "continue", "previous_message_id": "msg_xxx_from_create" }
}

Continue isteğinde system ve tools alanlarını göndermeyin; "system": null kullanmak bile 400 hatasına yol açıyor. Akış kullanan isteklerde devam etmeden önce message_stop olayını bekleyin. Kullanılabilir devam kimliği message_start içinde geliyor.

Thread devam ederken hangi alanlar değiştirilebilir?

Anthropic, create isteğinin bazı bölümlerinden bir parmak izi oluşturuyor. Parmak izi alınan bir değeri değiştirirseniz thread_fingerprint_mismatch hatası döner ve yeni bir thread başlatmanız gerekir.

Extended-thinking modellerinde daha dikkatli olmanız gerekiyor: system veya tools alanlarını değiştirmek, önceki thinking / redacted_thinking bloklarını geçersiz kılabilir. Süre dolduktan sonra yapılan tam replay isteği 400 döndürürse eski thinking bloklarını aynen yeniden göndermek yerine replay geçmişinden çıkarın.

5 dakika kuralı ve mutlaka eklemeniz gereken replay mekanizması

Threads özelliğini en iyi ihtimalle çalışan bir mekanizma olarak ele alın. Tam geçmişi, system ve tools alanlarını, ayrıca dosya referanslarını yerel olarak saklayın; çünkü sunucudaki kaydın kesinleştiği ancak bir sonraki continuation isteği başarıyla tamamlandığında doğrulanıyor. Dosyalar referansla tutuluyor; thread sırasında bir dosyayı silerseniz devam isteği başarısız olur.

Süre sayacı, kaydedilen her yanıtla sıfırlanıyor. 5 dakika boşta kaldıktan sonra yapılan ilk continue isteği 404 döndürür; bunun üzerine tüm konuşmayı yeni bir create isteği olarak yeniden göndermeniz gerekir. Veriler son kullanımdan en geç 1 saat sonra silinir.

Doküman özetine göre başarısız thread istekleri model çalıştırılmadan önce durduruluyor; bu nedenle token tüketmiyor ve süre sayacını sıfırlamıyor. Bir sonraki turu kabul etmeden önce son başarılı yanıtın ID'sini atomik olarak kaydedin. Araç eylemleri yan etkiye sahipse replay işlemlerini idempotent olacak şekilde koruyun.

Python'da replay yapısının temel biçimi şöyle (yalnızca doğrulanmış thread_not_found durumunu ele alıyor; fingerprint, eşzamanlılık ve desteklenmeyen istek hataları için ayrı dallar gerekir):

try:
    resp = client.beta.messages.create(
        model="claude-opus-5-5",
        messages=[new_msg],  # delta only
        thread={"type": "continue", "previous_message_id": last_id},
        extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
    )
except NotFoundError:  # thread_not_found after checking identity/config
    resp = client.beta.messages.create(
        model="claude-opus-5-5",
        system=SYSTEM, tools=TOOLS,
        messages=full_history + [new_msg],  # you stored this
        thread={"type": "create"},
        extra_headers={"anthropic-beta": "message-threads-2026-08-12"},
    )

Proxy ve anahtar rotasyonunda 404 tuzağı

Bu davranış operatörler tarafından bildirildi; henüz resmî dokümantasyona eklenmiş değil: Bir thread, onu oluşturan kuruluş, çalışma alanı ve kimlik bilgisine bağlanıyor. Her istekte API anahtarını değiştiren bir relay kullanırsanız thread'i A anahtarıyla oluşturup B anahtarıyla devam ettirirsiniz. Sonuç, süre dolumuyla tamamen aynı görünür: sürekli 404 alırsınız, ardından tüm geçmiş yeniden gönderilir ve gecikme avantajı ortadan kalkar.

"thread'i oluşturan key ve workspace'e bağlı; key değişirse 404 thread_not_found dönüyor. Anahtar rotasyonu yapan bir ara sunucu önce 404 alıyor, sonra tüm isteği yeniden gönderiyor." — @ak12kpoot (proxy davranışı hakkında Çinli geliştirici notu)

Bir thread'i tek bir anahtara sabitleyin veya havuzlanmış rotalarda threads özelliğini devre dışı bırakın.

Threads nerede çalışıyor, neleri desteklemiyor ve şimdi geçmeli misiniz?

Message threads; Claude API, AWS üzerindeki Claude Platform, Anthropic tarafından yönetilen Google Cloud Claude Models ve Claude in Microsoft Foundry üzerinde kullanılabiliyor. Beta kapsamındaki tüm modeller destekleniyor; ayrıca ayrı bir model izin listesi veya belirtilmiş bir bekleme listesi bulunmuyor.

Ancak kullanılamadığı alanlar, ilk kullanım planı açısından daha önemli:

Karar vermek için kısa kontrol listesi

• Şimdi kullanın: Aktif kodlama ajanları, ekran görüntüleriyle çalışan bilgisayar kullanımı döngüleri veya 5 dakikadan kısa aralıklarla onlarca tur yapan, belge ağırlıklı akışlar. Prompt caching ile birlikte kullanın ve mutlaka bir replay yolu ekleyin.
• Şimdilik bekleyin: İnsan temposundaki sohbetler, duraklatılmış iş akışları, batch işlem hatları, ZDR/HIPAA iş yükleri veya Bedrock dağıtımları.
• Birlikte kullanırken dikkat edin: Her istekte üst düzey cache_control kullanmak 4 breakpoint sınırına dahil olur. Create isteğindeki system/tools breakpoint'leri de her continue isteğinde yeniden hesaba katılır. Sınırı aşarsanız thread_unsupported_request hatası alırsınız; bu nedenle iki özelliği birlikte etkinleştirmeden önce breakpoint'leri birleştirin.

Ayrıca bakın: Claude API fiyatlandırma rehberi 2026, Claude Skills API rehberi.

Sık sorulan sorular

Hangi beta başlığını ve parametreyi kullanmalıyım?

Thread içindeki her istekte anthropic-beta: message-threads-2026-08-12 başlığını gönderin. İlk çağrıda thread: { "type": "create" }, sonraki çağrılarda ise thread: { "type": "continue", "previous_message_id": "<last response id>" } kullanın.

Bir thread'in süresi dolduğunda ne olur?

Bir sonraki continue isteği 404 thread_not_found hatası döndürür. Tüm messages içeriğini ve ilk istekteki system/tools alanlarını yeni bir create isteğiyle yeniden gönderin. Süre, 5 dakika boşta kalmanın ardından dolar; veriler son kullanımdan en geç 1 saat sonra silinir.

Thread'leri listeleyebilir, inceleyebilir veya silebilir miyim?

Hayır. Messages API thread'leri için bir yönetim API'si yok. Kalıcı kayıt olarak yalnızca yerel geçmişinize güvenebilirsiniz.

Amazon Bedrock üzerinde çalışıyor mu?

Hayır. Desteklenen yüzeyler Claude API, AWS Claude Platform, Microsoft Foundry ve Anthropic tarafından yönetilen Google Cloud'dur. Bedrock isteklerinde tam geçmişi göndermeye devam etmelisiniz.

Thread devam ederken system prompt'u veya araçları değiştirebilir miyim?

Hayır. Yeni system/tools değerleriyle yeni bir thread oluşturun. Continue isteğinde değişen değerleri göndermek thread_fingerprint_mismatch hatasına yol açar. Aynı kural model, tool_choice ve thinking yapılandırması için de geçerlidir.

Streaming, araçlar ve MCP ile çalışıyor mu?

Evet, ancak bazı kuralları var: Devam etmeden önce message_stop olayını bekleyin, MCP URL'lerini/token'larını ve container kimliklerini her turda yeniden gönderin. Ayrıca fallbacks alanını ya her isteğe ekleyin ya da hiçbirinde kullanmayın; geri dönüş modeli tarafından üretilen yanıt saklanmaz ve yeniden oynatılması gerekir.