Claude Message Threads API: Leitfaden

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, 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 behandelt die Kontextseite.

Threads ändern weder Preise noch Rate-Limits (Seite Message threads, 4.11.2026). Aktuelle Preise stehen unter Preise.

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

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:

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

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.

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
• Anthropic: Prompt-Caching
• Anthropic: Preise der Claude API
• Anthropic: API-Versionierung