# Claude Message Threads API rehberi

> Claude API'deki message threads: beta başlığı, create ve continue istekleri, yeniden gönderilmesi gereken alanlar, süre dolumu ve 404 sonrası ne yapılır.

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

---

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](https://omniakey.com/tr/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](https://omniakey.com/tr/blog/reduce-claude-code-token-usage) 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](https://omniakey.com/tr/pricing) 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).

```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"}
  }'
```

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

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

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

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

|Grup|Alanlar|Kural|
|-|-|-|
|Yalnızca create|`system`, `tools`|Yalnızca create isteğinde; continue isteğinde ikisinden birini göndermek, `null` olsa bile 400 döndürür.|
|Sabit|`model`, `tool_choice`, `thinking`, her sunucunun yetkilendirme token'ı hariç `mcp_servers`, `context_management`, `output_config`, `container` içindeki `skills`, üst düzey `cache_control` ve `anthropic-beta` değerler kümesi|Her seferinde aynı değer. Farklı değer 400 döndürür ve hangi alanın farklı olduğunu söyler.|
|Serbest|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` ve adı olmayan alanlar|İstediğiniz zaman değiştirin.|

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](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: prompt önbelleği](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: Claude API fiyatları](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: API sürümleri](https://platform.claude.com/docs/en/api/versioning)