# Claude Message Threads API: Leitfaden

> Message Threads in der Claude API: Beta-Header, create- und continue-Requests, Pflichtfelder beim Nachsenden, Ablaufzeit und was nach einem 404 hilft.

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

---

Die Message-Threads-API von Claude lässt dich eine lange Unterhaltung einmal senden und in jedem weiteren Turn nur die neuen Nachrichten. Setze `"thread": {"type": "create"}` in die erste Messages-Anfrage und den Beta-Header `message-threads-2026-08-12`, dann hält die API die Unterhaltung im Speicher und die nächste Anfrage überträgt weniger (Anthropics Seite zu Message threads, 4.11.2026).

Sie ist bei allen Modellen eine Beta. 17 Modell-IDs können sie nutzen, darunter [Claude Opus 5.5](https://omniakey.com/de/claude-opus-5-5), das der Code unten aufruft. Der Beta-Header steht in jeder Anfrage eines Threads.

## Was ein Thread spart

Ohne Thread trägt jeder Turn das ganze Transkript: System-Prompt, Tool-Definitionen, jede frühere Nachricht und jedes Tool-Ergebnis. Ein Thread speichert diese Unterhaltung samt Claudes Antwort unter der `id` der Antwort, und eine continue-Anfrage sendet nur, was seither passiert ist (Seite Message threads, 4.11.2026). Pro Turn geht weniger über die Leitung.

Prompt-Caching hilft derselben Unterhaltung anders. Ein Cache-Treffer macht wiederholte Eingabe billiger: bei Opus 5.5 kostet sie 0,20 USD pro Million Token statt 4 USD für frische Eingabe (Anthropics Preisseite, 4.11.2026). Die Anfrage trägt diese Eingabe trotzdem. Der Thread senkt, was du sendest; das Caching senkt den Preis des Wiederholten. Lange Sitzungen brauchen beides, und [Claude-Code-Token sparen](https://omniakey.com/de/blog/reduce-claude-code-token-usage) behandelt die Kontextseite.

Threads ändern weder Preise noch Rate-Limits (Seite Message threads, 4.11.2026). Aktuelle Preise stehen unter [Preise](https://omniakey.com/de/pricing).

Caching bleibt deine Aufgabe. Sende in jeder Anfrage ein `cache_control` auf oberster Ebene, dann wendet die API es auf den letzten cachebaren Block der `messages` dieser Anfrage an. Vier Haltepunkte sind die Regel des Prompt-Cachings für die ganze Plattform, und das automatische Caching belegt einen davon (Anthropics Prompt-Caching-Seite, 4.11.2026). So verteilst du sie:

1. das `cache_control` auf oberster Ebene, ein Platz in jeder Anfrage des Threads;
2. eins auf `system`, mit der create-Anfrage gesendet;
3. eins auf `tools`, ebenfalls bei create;
4. eins auf der neuesten Nachricht.

Haltepunkte auf früher gespeicherten Nachrichten liegen außerhalb dieses Budgets, weil eine continue-Anfrage nur neue Nachrichten sendet. Einmal gesendet, bleibt ein Haltepunkt, wo er ist. Beim erneuten Senden einer Unterhaltung entfernst du die Haltepunkte aus den früheren Nachrichten und lässt einen auf dem letzten Block (Seite Message threads, 4.11.2026).

## Ersten Turn anlegen, dann fortsetzen

Drei Schritte:

1. Anthropic-Schlüssel in `ANTHROPIC_API_KEY` legen.
2. Die ganze Unterhaltung senden, mit `system` und `tools`, falls du sie nutzt, plus `"thread": {"type": "create"}`.
3. Nur die Nachrichten seit der letzten Antwort senden, plus `"thread": {"type": "continue", "previous_message_id": "<previous id>"}`, und `system` und `tools` weglassen.

Jede Anfrage trägt den Beta-Header und `anthropic-version: 2026-10-21`, die aktuelle Version (Anthropics Seite zur Versionierung, 4.11.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"}
  }'
```

Speichere die `id` aus dieser Antwort. Die nächste Anfrage sendet nur die neue Nachricht:

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

Behalte die neueste `id` jeder Antwort: ein Thread nimmt nur Anhänge auf, jede Antwort-`id` lässt sich einmal fortsetzen, und die nächste Anfrage braucht die letzte (Seite Message threads, 4.11.2026).

Brauchst du einen anderen Weg zu einem API-Schlüssel, verkauft OmniaKey Zugang zur Claude API mit denselben Modell-IDs, der Request-Body bleibt also gleich. Threads sind auf Anthropics Seite eine Beta; prüfe vor dem Produktivbetrieb, ob dein Proxy das Feld `thread` unverändert durchreicht.

Das Python-SDK führt die IDs für dich. Baue einen Helper mit `client.beta.messages.thread(...)`, der nur den Aufruf vorbereitet, und sende jeden Turn mit `thread.send()`. Der Helper setzt den Beta-Header, legt beim ersten Turn an, setzt nur mit neuen Nachrichten fort und sendet die ganze Unterhaltung einmal in einer neuen create-Anfrage erneut, wenn ein continue `thread_not_found`, `thread_already_continued` oder `thread_continue_in_flight` liefert (Seite Message threads, 4.11.2026).

```python
import anthropic

client = anthropic.Anthropic()  # liest ANTHROPIC_API_KEY

# Der Helper sendet noch nichts; er hält die Felder, die jeder Turn wiederverwendet.
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)  # beim nächsten Mal von dieser id aus fortsetzen
```

Wir haben diese Anfragen nicht gegen die Anthropic-API ausgeführt; die Form kommt von Anthropics Seite zu Message threads. Für Streams liefern `thread.stream(...)` und `stream.get_final_message()` denselben Ablauf, und `thread.previous_message_id` gibt die ID zurück, wenn du sie lieber selbst mitführst.

## Was du nachsendest und was nie

Feste Felder sendest du in jeder Anfrage mit denselben Werten, `system` und `tools` nur in der create-Anfrage, und freie Felder dürfen sich von Turn zu Turn ändern.

|Gruppe|Felder|Regel|
|-|-|-|
|Nur create|`system`, `tools`|Nur in der create-Anfrage; wer eins davon in einer continue-Anfrage sendet, auch als `null`, bekommt 400.|
|Fest|`model`, `tool_choice`, `thinking`, `mcp_servers` außer dem Autorisierungstoken des jeweiligen Servers, `context_management`, `output_config`, die `skills` in `container`, das `cache_control` auf oberster Ebene und die Menge der `anthropic-beta`-Werte|Jedes Mal derselbe Wert. Ein anderer Wert ergibt 400, und die Meldung nennt das abweichende Feld.|
|Frei|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` und unbenannte Felder|Jederzeit änderbar.|

Das 400 für ein geändertes festes Feld trägt `thread_fingerprint_mismatch`, und die Meldung listet die abweichenden Felder. Um einen dieser Werte zu ändern, startest du einen neuen Thread mit der ganzen Unterhaltung und dem neuen Wert.

Fehlt `previous_message_id`, gibt continue ein 400 zurück, dessen Body eine message, aber keinen `error_code` enthält; `system` oder `tools` mitzusenden wirkt genauso. Ein continue soll genau die Nachrichten seit der letzten Antwort tragen.

`mcp_servers` ist fest, doch Server-URLs und Autorisierungstoken stehen nur in deiner Anfrage, also sende die Liste in jeder Anfrage mit MCP; ein Token kann zwischen Anfragen wechseln. Die `id` des Containers steht ebenfalls nur in deiner Anfrage, also sende `container` jedes Mal (Seite Message threads, 4.11.2026).

Server-seitiges Fallback wird bei create festgelegt: sende `fallbacks` in jeder Anfrage des Threads oder in keiner. Der Wert darf sich zwischen Turns ändern, doch das Feld hinzuzufügen oder wegzulassen ergibt `thread_fingerprint_mismatch`.

## Ablauf, erneutes Senden und der 404

Ein Thread läuft 5 Minuten nach seiner letzten Anfrage ab, und die API löscht ihn höchstens 1 Stunde nach der letzten Nutzung. Jede gespeicherte Antwort startet die 5 Minuten neu. Threads sind nicht für Zero Data Retention geeignet: Unterhaltung, System-Prompt und Tools liegen verschlüsselt im Speicher und werden nie in dauerhaften Speicher geschrieben (Seite Message threads, 4.11.2026).

Keine Angabe in der Antwort sagt, ob die API einen Turn gespeichert hat, weder bei create noch bei continue. Du erfährst es mit der nächsten continue-Anfrage, also bleibt deine Anwendung die Quelle der Wahrheit und führt eine eigene Kopie jeder Nachricht (Seite Message threads, 4.11.2026).

Wenn continue 404 `thread_not_found` liefert, sende die ganze Unterhaltung in einer neuen create-Anfrage und setze mit der `id` dieser Antwort fort. Dieselbe 404 kommt in all diesen Fällen:

- der Thread ist abgelaufen;
- der vorige Turn wurde bedient und dann verworfen, etwa ein Tool-Aufruf, den `max_tokens` abgeschnitten hat;
- ein Fallback-Modell hat die vorige Antwort geschrieben;
- die vorige Antwort wird noch erzeugt;
- die Anfrage kam aus einer anderen Organisation, einem anderen Workspace, einem anderen Nutzer oder Workspace-Schlüssel;
- die neuen Nachrichten bringen Inhalt, den die gespeicherte Unterhaltung nicht hat, etwa das erste Bild in einer Unterhaltung ohne Bilder.

Die ganze Unterhaltung erneut zu senden ist immer sicher und repariert jeden dieser Fälle.

Streaming fügt eine Regel hinzu: setze erst nach `message_stop` mit der `id` der Antwort fort, denn ein früher gesendetes continue kann 404 liefern. Bricht der Stream einer continue-Anfrage vor `message_stop` ab, sende dieselbe continue-Anfrage erneut, und sende alles neu, wenn das `thread_already_continued` oder `thread_continue_in_flight` ergibt. Einen abgebrochenen Stream lässt der SDK-Helper dir zum Wiederholen.

Drei weitere Fälle haben ihren eigenen Weg:

- `pause_turn`: mit der `id` dieser Antwort und `"messages": []` fortsetzen. Ergibt das 404, sende alles neu und schließe die pausierte Antwort ein.
- `stop_reason: "refusal"`: starte einen neuen Thread ohne den Turn, der ihn ausgelöst hat; die API hat den abgelehnten Turn vielleicht schon.
- ein `fallback_message`-Eintrag in `usage.iterations` oder im letzten `message_delta` eines Streams markiert eine Fallback-Antwort: alles neu senden.

## Fehler

Alle fünf Thread-Fehler kommen zurück, bevor das Modell läuft: die Anfrage verbraucht keine Token, und der Thread behält seine Ablaufzeit. `error.type` ist `invalid_request_error` bei den 400ern und `not_found_error` beim 404 (Seite Message threads, 4.11.2026).

- **404, `thread_not_found`**: Die API kann diesen Thread nicht fortsetzen. Sende die ganze Unterhaltung in einer neuen create-Anfrage.
- **400, `thread_fingerprint_mismatch`**: Ein festes Feld weicht von dem Wert ab, der mit dem Thread gespeichert wurde. Gleich halten oder einen neuen Thread starten.
- **400, `thread_already_continued`**: Diese Antwort-`id` wurde schon einmal verwendet. Mit der neuesten `id` fortsetzen und alles neu senden, wenn du sie nie bekommen hast.
- **400, `thread_continue_in_flight`**: Ein weiteres continue von derselben `id` läuft noch, meist dein eigener früherer Versuch. Beenden lassen oder alles neu senden.
- **400, `thread_unsupported_request`**: Die Anfrage nutzt eine Funktion oder eine Organisationseinstellung, die Threads nicht unterstützen. `error.details.unsupported` nennt eins von `context_management`, `cache_control`, `fallbacks`, `hipaa` oder `inference_hooks`; die Liste kann wachsen, also sende bei einem unbekannten Wert die ganze Unterhaltung ohne `thread`.

Message Batches lehnt das Feld `thread` ab (ein Batch-Element damit scheitert mit `invalid_request_error`), und Token-Zählung sowie Kompaktierung liefern 400; ebenso Kontextbearbeitung außer `clear_thinking_20251015` mit `keep: "all"`. HIPAA-fähige Organisationen und Organisationen mit aktiven Inference hooks sind ausgeschlossen. Auflisten, Lesen und Löschen eines Threads gibt es in der API nicht.

## Häufige Fragen

### Was ist die Claude Message Threads API?

Eine Beta-Funktion der Messages API, die eine Unterhaltung auf Anthropics Seite speichert, sodass spätere Turns nur neue Nachrichten senden. Der Beta-Header ist `message-threads-2026-08-12`, und jede Anfrage fügt ein `thread`-Objekt mit `type` gleich `create` oder `continue` hinzu.

### Funktioniert Message Threads mit Prompt-Caching?

Ja. Ein Thread cached deinen Prompt nicht für dich: sende in jeder Anfrage ein `cache_control` auf oberster Ebene und bleib bei vier Haltepunkten. Haltepunkte auf gespeicherten Nachrichten zählen nicht mit; der oberste und die auf `system` oder `tools` zählen.

### Kann ich mitten im Thread das Modell wechseln?

Ein Modellwechsel braucht einen neuen Thread. `model` ist ein festes Feld, ein anderer Wert ergibt 400 `thread_fingerprint_mismatch`; starte einen neuen Thread mit der ganzen Unterhaltung und dem neuen Modell.

### Warum liefert continue ein 400 ohne error\_code?

Dem continue fehlt `previous_message_id`, oder es enthält `system` oder `tools`, auch als `null`. Diese 400er tragen eine message und lassen `error_code` weg, also lies den Text.

### Wie lange hält ein Thread, und was passiert beim Ablauf?

Ein Thread läuft 5 Minuten nach der letzten Anfrage ab und wird höchstens 1 Stunde nach der letzten Nutzung gelöscht. Danach liefert continue 404 `thread_not_found`; sende die ganze Unterhaltung in einer neuen create-Anfrage und setze mit ihrer `id` fort.

## Geprüfte Quellen

- [Anthropic: message threads](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: Prompt-Caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: Preise der Claude API](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: API-Versionierung](https://platform.claude.com/docs/en/api/versioning)