Claude Message Threads API: guida ai thread

L'API Claude Message Threads ti permette di inviare una conversazione lunga una volta sola e, a ogni turno successivo, mandare solo i messaggi nuovi. Aggiungi "thread": {"type": "create"} alla prima richiesta Messages e l'header beta message-threads-2026-08-12: l'API tiene la conversazione in memoria e la richiesta successiva invia meno contenuto (pagina Message threads di Anthropic, 4 novembre 2026).

È beta su tutti i modelli. 17 ID di modello possono usarla, incluso Claude Opus 5.5, che il codice qui sotto chiama. L'header beta accompagna ogni richiesta di un thread.

Cosa risparmia un thread

Senza thread, ogni turno porta l'intera trascrizione: il system prompt, le definizioni degli strumenti, tutti i messaggi precedenti e tutti i risultati degli strumenti. Un thread archivia quella conversazione, risposta di Claude compresa, sotto l'id della risposta, e una richiesta continue invia solo ciò che è successo dopo (pagina Message threads, 4 novembre 2026). Meno contenuto a ogni turno.

La cache dei prompt aiuta la stessa conversazione da un altro lato. Un cache hit rende più economico l'input ripetuto: su Opus 5.5, 0,20 USD per milione di token contro 4 USD per un input nuovo (pagina dei prezzi di Anthropic, 4 novembre 2026). La richiesta porta comunque quell'input. Il thread riduce quello che invii; la cache abbassa il prezzo di ciò che si ripete. Le sessioni lunghe vogliono entrambi, e ridurre il consumo di token di Claude Code copre il lato contesto.

I thread non cambiano né i prezzi né i limiti di frequenza (pagina Message threads, 4 novembre 2026). Le tariffe attuali sono nella pagina prezzi.

La cache la gestisci tu. Invia un cache_control di primo livello in ogni richiesta e l'API lo applica all'ultimo blocco messages memorizzabile di quella richiesta. Il limite di quattro breakpoint è una regola della cache dei prompt valida per tutta la piattaforma, e la cache automatica ne occupa uno (pagina della cache dei prompt di Anthropic, 4 novembre 2026). Distribuiscili così:

1. il cache_control di primo livello, un punto in ogni richiesta del thread;
2. uno su system, inviato con la richiesta create;
3. uno su tools, anche alla create;
4. uno sul messaggio più recente.

I breakpoint sui messaggi già archiviati restano fuori da questo budget, perché una richiesta continue invia solo i messaggi nuovi. Un breakpoint inviato resta dov'è. Quando reinvii una conversazione, togli i punti dai messaggi precedenti e lascia un punto sull'ultimo blocco (pagina Message threads, 4 novembre 2026).

Crea il primo turno, poi continua

Tre passaggi:

1. Metti la tua chiave Anthropic in ANTHROPIC_API_KEY.
2. Invia la conversazione completa, con system e tools se li usi, più "thread": {"type": "create"}.
3. Invia solo i messaggi dall'ultima risposta, più "thread": {"type": "continue", "previous_message_id": "<previous id>"}, e lascia fuori system e tools.

Ogni richiesta porta l'header beta e anthropic-version: 2026-10-21, la versione attuale (pagina delle versioni di Anthropic, 4 novembre 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"}
  }'

Conserva l'id di quella risposta. La richiesta successiva invia solo il messaggio nuovo:

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

Tieni l'id più recente di ogni risposta: un thread accetta solo aggiunte, ogni id di risposta si continua una volta sola, e la richiesta successiva deve usare l'ultimo (pagina Message threads, 4 novembre 2026).

Se ti serve un'altra strada per una chiave API, OmniaKey vende accesso all'API Claude con gli stessi ID di modello, quindi il corpo della richiesta non cambia. I thread sono beta dalla parte di Anthropic, quindi prima di dipenderne in produzione controlla che l'intermediario che usi lasci passare il campo thread così com'è.

L'SDK Python segue gli id per te. Prepara un helper con client.beta.messages.thread(...), che si limita a preparare la chiamata, e invia ogni turno con thread.send(). L'helper aggiunge l'header beta, crea al primo turno, continua con i soli messaggi nuovi e una volta reinvia tutta la conversazione in una nuova richiesta create quando una continue dà thread_not_found, thread_already_continued o thread_continue_in_flight (pagina Message threads, 4 novembre 2026).

import anthropic

client = anthropic.Anthropic()  # legge ANTHROPIC_API_KEY

# L'helper non invia ancora nulla; conserva i campi che ogni turno riusa.
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)  # la prossima volta continua da questo id

Non abbiamo eseguito queste richieste contro l'API di Anthropic; la forma viene dalla pagina Message threads di Anthropic. Per lo streaming, thread.stream(...) e stream.get_final_message() danno lo stesso flusso, e thread.previous_message_id restituisce l'id se preferisci seguirlo da solo.

Cosa reinviare e cosa mai

Invia i campi fissi con gli stessi valori in ogni richiesta, system e tools solo nella richiesta create, e lascia che i campi liberi cambino da un turno all'altro.

Il 400 di un campo fisso modificato porta thread_fingerprint_mismatch, e il messaggio elenca i campi che differiscono. Per cambiare uno di questi valori, apri un nuovo thread con la conversazione completa e il nuovo valore.

Se manca previous_message_id, la richiesta continue dà 400 con un message nel corpo ma nessun error_code; aggiungere system o tools fa lo stesso. Una richiesta continue deve portare esattamente i messaggi dall'ultima risposta.

mcp_servers è fisso, ma gli URL dei server e i token di autorizzazione vivono solo nella tua richiesta, quindi invia la lista in ogni richiesta che usa MCP; un token può cambiare tra due richieste. Anche l'id del container vive solo nella tua richiesta, quindi invia container ogni volta (pagina Message threads, 4 novembre 2026).

Il fallback lato server si decide alla create: invia fallbacks in ogni richiesta del thread o in nessuna. Il valore può cambiare tra i turni, ma aggiungere o togliere il campo dà thread_fingerprint_mismatch.

Scadenza, reinvio e il 404

Un thread scade 5 minuti dopo l'ultima richiesta, e l'API lo elimina al più tardi 1 ora dopo l'ultimo uso. Ogni risposta archiviata riavvia i 5 minuti. I thread non rientrano nella conservazione zero dei dati: la conversazione, il system prompt e gli strumenti restano in memoria, cifrati, e non vengono mai scritti su uno storage durevole (pagina Message threads, 4 novembre 2026).

Nessun campo della risposta dice se l'API ha archiviato un turno, né alla create né alla continue. Lo scopri alla richiesta continue successiva, quindi la tua applicazione resta la fonte di verità e tiene una propria copia di ogni messaggio (pagina Message threads, 4 novembre 2026).

Quando una richiesta continue dà 404 thread_not_found, invia la conversazione completa in una nuova richiesta create e riparti dall'id di quella risposta. L'API dà lo stesso 404 in tutti questi casi:

• il thread è scaduto;
• il turno precedente è stato servito e poi scartato, per esempio una chiamata a uno strumento tagliata da max_tokens;
• la risposta precedente l'ha scritta un modello di fallback;
• la risposta precedente è ancora in generazione;
• la richiesta arriva da un'altra organizzazione, workspace, utente o chiave di workspace;
• i messaggi nuovi portano contenuto che la conversazione archiviata non ha, come la prima immagine di una conversazione che non ne aveva.

Reinviare la conversazione completa è sempre sicuro e sistema ognuno di questi casi.

Lo streaming aggiunge una regola: riparti dall'id della risposta solo dopo message_stop, perché una continue inviata prima può dare 404. Se lo stream di una richiesta continue si interrompe prima di message_stop, invia di nuovo la stessa richiesta continue, e reinvia tutto se questo dà thread_already_continued o thread_continue_in_flight. Lo stream interrotto l'helper dell'SDK lo lascia al tuo retry.

Altri tre casi hanno una strada propria:

• pause_turn: riparti dall'id di quella risposta con "messages": []. Se dà 404, reinvia tutto includendo la risposta in pausa.
• stop_reason: "refusal": apri un nuovo thread senza il turno che l'ha provocato; l'API potrebbe già avere il turno rifiutato.
• una voce fallback_message in usage.iterations, o nell'ultimo message_delta di uno stream, segnala una risposta di fallback: reinvia tutto.

Errori

I cinque errori di thread tornano prima che il modello giri: la richiesta non consuma token e il thread tiene la sua scadenza. error.type vale invalid_request_error per i 400 e not_found_error per il 404 (pagina Message threads, 4 novembre 2026).

• 404, thread_not_found: l'API non può continuare questo thread. Invia la conversazione completa in una nuova richiesta create.
• 400, thread_fingerprint_mismatch: un campo fisso è cambiato rispetto al valore salvato con il thread. Tienilo identico o apri un nuovo thread.
• 400, thread_already_continued: quell'id di risposta è già stato usato una volta. Riparti dall'id più recente e reinvia tutto se non l'hai mai ricevuto.
• 400, thread_continue_in_flight: un'altra continue sullo stesso id è ancora in corso, di solito il tuo tentativo precedente. Lasciala finire o reinvia tutto.
• 400, thread_unsupported_request: la richiesta usa una funzione o un'impostazione dell'organizzazione che i thread non supportano. error.details.unsupported nomina uno tra context_management, cache_control, fallbacks, hipaa e inference_hooks; l'elenco può allungarsi, quindi se un valore ti è sconosciuto invia la conversazione completa senza thread.

Message Batches rifiuta il campo thread (un elemento di batch che lo porta fallisce con invalid_request_error), e il conteggio dei token e la compattazione danno 400; lo stesso vale per la modifica del contesto diversa da clear_thinking_20251015 con keep: "all". Le organizzazioni pronte per HIPAA e quelle con Inference hooks attivi sono escluse. Elencare, leggere ed eliminare un thread non esistono nell'API.

Domande frequenti

Che cos'è l'API Claude Message Threads?

È una funzione beta dell'API Messages che archivia una conversazione dalla parte di Anthropic, così i turni successivi inviano solo i messaggi nuovi. L'header beta è message-threads-2026-08-12, e ogni richiesta aggiunge un oggetto thread con type uguale a create o continue.

I thread funzionano con la cache dei prompt?

Sì. Il thread non mette in cache il tuo prompt al posto tuo: invia un cache_control di primo livello in ogni richiesta e resta entro quattro breakpoint. I punti sui messaggi archiviati non contano; quello di primo livello e quelli su system o tools contano.

Posso cambiare modello a metà thread?

Cambiare modello richiede un nuovo thread. model è un campo fisso, quindi un valore diverso dà 400 thread_fingerprint_mismatch; apri un nuovo thread con la conversazione completa e il nuovo modello.

Perché una continue dà 400 senza error_code?

Manca previous_message_id, oppure la richiesta contiene system o tools, anche come null. Quei 400 portano un message e omettono error_code, quindi leggi il testo.

Quanto dura un thread e cosa succede alla scadenza?

Un thread scade 5 minuti dopo l'ultima richiesta e viene eliminato al più tardi 1 ora dopo l'ultimo uso. Dopo, una continue dà 404 thread_not_found; invia la conversazione completa in una nuova richiesta create e riparti dal suo id.

Fonti verificate

• Anthropic: message threads
• Anthropic: cache dei prompt
• Anthropic: prezzi dell'API Claude
• Anthropic: versioni dell'API