Claude Message Threads API: guia de threads

A API Claude Message Threads deixa você enviar uma conversa longa uma vez e, a cada turno seguinte, mandar só as mensagens novas. Coloque "thread": {"type": "create"} na primeira requisição de Messages e o cabeçalho beta message-threads-2026-08-12: a API guarda a conversa na memória e a requisição seguinte envia menos conteúdo (página Message threads da Anthropic, 4 de novembro de 2026).

É beta em todos os modelos. 17 IDs de modelo podem usá-la, incluindo Claude Opus 5.5, que o código abaixo chama. O cabeçalho beta vai em toda requisição de uma thread.

O que uma thread economiza

Sem thread, cada turno carrega a transcrição inteira: o system prompt, as definições de ferramentas, todas as mensagens anteriores e todo resultado de ferramenta. Uma thread guarda essa conversa, incluindo a resposta do Claude, sob o id da resposta, e uma requisição continue envia só o que aconteceu desde então (página Message threads, 4 de novembro de 2026). Menos conteúdo por turno.

O cache de prompt ajuda a mesma conversa por outro lado. Um acerto de cache deixa a entrada repetida mais barata: no Opus 5.5, US$ 0,20 por milhão de tokens contra US$ 4 para entrada nova (página de preços da Anthropic, 4 de novembro de 2026). A requisição continua carregando essa entrada. A thread reduz o que você envia; o cache reduz o preço do que se repete. Sessões longas querem os dois, e reduzir o consumo de tokens do Claude Code cobre o lado do contexto.

Threads não mudam preço nem limites de taxa (página Message threads, 4 de novembro de 2026). Os preços atuais estão em preços.

O cache é por sua conta. Envie um cache_control de nível superior em cada requisição e a API o aplica ao último bloco cacheável dos messages daquela requisição. O limite de quatro pontos de quebra é uma regra do cache de prompt da plataforma inteira, e o cache automático usa um dos quatro (página de cache de prompt da Anthropic, 4 de novembro de 2026). Distribua assim:

1. o cache_control de nível superior, um ponto em cada requisição da thread;
2. um em system, enviado com a requisição create;
3. um em tools, também no create;
4. um na mensagem mais recente.

Pontos de quebra em mensagens já guardadas ficam fora desse limite, porque uma requisição continue envia só mensagens novas. Uma vez enviado, o ponto fica onde está. Ao reenviar uma conversa, tire os pontos das mensagens anteriores e deixe um no último bloco (página Message threads, 4 de novembro de 2026).

Crie o primeiro turno e continue

Três passos:

1. Coloque sua chave da Anthropic em ANTHROPIC_API_KEY.
2. Envie a conversa completa, com system e tools se você os usa, mais "thread": {"type": "create"}.
3. Envie só as mensagens desde a última resposta, mais "thread": {"type": "continue", "previous_message_id": "<previous id>"}, e deixe system e tools de fora.

Cada requisição leva o cabeçalho beta e anthropic-version: 2026-10-21, a versão atual (página de versões da Anthropic, 4 de novembro de 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"}
  }'

Guarde o id dessa resposta. A próxima requisição envia só a mensagem nova:

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

Guarde o id mais recente de cada resposta: uma thread só aceita acréscimos, cada id de resposta continua uma vez e a requisição seguinte precisa usar o último (página Message threads, 4 de novembro de 2026).

Se você precisa de outro caminho para uma chave de API, a OmniaKey vende acesso à API Claude com os mesmos IDs de modelo, então o corpo da requisição não muda. Threads são beta do lado da Anthropic, então antes de depender delas em produção confira se o intermediário que você usa repassa o campo thread sem alterar.

O SDK de Python guarda os ids por você. Monte um helper com client.beta.messages.thread(...), que só prepara a chamada, e envie cada turno com thread.send(). O helper acrescenta o cabeçalho beta, cria no primeiro turno, continua só com as mensagens novas e reenvia a conversa completa uma vez numa nova requisição create quando um continue devolve thread_not_found, thread_already_continued ou thread_continue_in_flight (página Message threads, 4 de novembro de 2026).

import anthropic

client = anthropic.Anthropic()  # lê ANTHROPIC_API_KEY

# O helper ainda não envia nada; ele guarda os campos que cada turno reutiliza.
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)  # da próxima vez, continue a partir deste id

Não executamos estas requisições contra a API da Anthropic; o formato vem da página Message threads da Anthropic. Para streaming, thread.stream(...) com stream.get_final_message() dá o mesmo fluxo, e thread.previous_message_id devolve o id quando você prefere acompanhar por conta própria.

O que reenviar e o que nunca reenviar

Envie os campos fixos com os mesmos valores em toda requisição, system e tools só na requisição create, e deixe os campos livres mudarem de um turno para o outro.

O 400 de um campo fixo alterado traz thread_fingerprint_mismatch, e a mensagem lista os campos que diferem. Para mudar um desses valores, comece uma thread nova com a conversa completa e o valor novo.

Se faltar previous_message_id, a requisição continue devolve 400 com uma message no corpo e nenhum error_code; incluir system ou tools faz o mesmo. Uma requisição continue deve levar exatamente as mensagens desde a última resposta.

mcp_servers é fixo, mas as URLs dos servidores e os tokens de autorização vivem só na sua requisição, então envie a lista em toda requisição que usa MCP; um token pode mudar entre requisições. O id do contêiner também vive só na sua requisição, então envie container toda vez (página Message threads, 4 de novembro de 2026).

O fallback do lado do servidor é decidido no create: envie fallbacks em toda requisição da thread ou em nenhuma. O valor pode mudar entre turnos, mas acrescentar ou tirar o campo devolve thread_fingerprint_mismatch.

Expiração, reenvio e o 404

Uma thread expira 5 minutos depois da última requisição, e a API a apaga no máximo 1 hora depois do último uso. Cada resposta guardada reinicia os 5 minutos. Threads não são elegíveis para retenção zero de dados: a conversa, o system prompt e as ferramentas ficam na memória, criptografados, e nunca são gravados em armazenamento durável (página Message threads, 4 de novembro de 2026).

Nenhum campo da resposta diz se a API guardou um turno, nem no create nem no continue. Você descobre na próxima requisição continue, então sua aplicação é a fonte da verdade e mantém a própria cópia de cada mensagem (página Message threads, 4 de novembro de 2026).

Quando um continue devolve 404 thread_not_found, envie a conversa completa numa nova requisição create e continue a partir do id dessa resposta. A API dá o mesmo 404 em todos estes casos:

• a thread expirou;
• o turno anterior foi atendido e depois descartado, como uma chamada de ferramenta cortada por max_tokens;
• um modelo de fallback escreveu a resposta anterior;
• a resposta anterior ainda está sendo gerada;
• a requisição veio de outra organização, espaço de trabalho, usuário ou chave de espaço de trabalho;
• as mensagens novas trazem conteúdo que a conversa guardada não tem, como a primeira imagem de uma conversa que não tinha nenhuma.

Reenviar a conversa completa é sempre seguro e conserta todos esses casos.

O streaming acrescenta uma regra: continue a partir do id da resposta só depois de message_stop, porque um continue enviado antes pode devolver 404. Se o stream de uma requisição continue cair antes de message_stop, envie a mesma requisição continue de novo, e reenvie tudo se isso devolver thread_already_continued ou thread_continue_in_flight. O helper do SDK deixa o stream derrubado para você tentar de novo.

Outros três casos têm caminho próprio:

• pause_turn: continue a partir do id dessa resposta com "messages": []. Se der 404, reenvie tudo incluindo a resposta pausada.
• stop_reason: "refusal": comece uma thread nova sem o turno que causou isso; a API pode já ter o turno recusado.
• uma entrada fallback_message em usage.iterations, ou no message_delta final de um stream, marca uma resposta de fallback: reenvie tudo.

Erros

Os cinco erros de thread voltam antes de o modelo rodar: a requisição não gasta tokens e a thread mantém o prazo. error.type é invalid_request_error nos 400 e not_found_error no 404 (página Message threads, 4 de novembro de 2026).

• 404, thread_not_found: a API não consegue continuar esta thread. Envie a conversa completa numa nova requisição create.
• 400, thread_fingerprint_mismatch: um campo fixo mudou em relação ao valor guardado com a thread. Mantenha-o idêntico ou comece uma thread nova.
• 400, thread_already_continued: esse id de resposta já foi usado uma vez. Continue a partir do id mais recente e reenvie tudo se nunca o recebeu.
• 400, thread_continue_in_flight: outro continue do mesmo id ainda está rodando, normalmente a sua tentativa anterior. Deixe terminar ou reenvie tudo.
• 400, thread_unsupported_request: a requisição usa um recurso ou um ajuste da organização que as threads não aceitam. error.details.unsupported nomeia um de context_management, cache_control, fallbacks, hipaa ou inference_hooks; a lista pode crescer, então se um valor parecer desconhecido, envie a conversa completa sem thread.

Message Batches recusa o campo thread (um item de lote com ele falha com invalid_request_error), e a contagem de tokens e a compactação devolvem 400; também a edição de contexto diferente de clear_thinking_20251015 com keep: "all". Organizações prontas para HIPAA e organizações com Inference hooks ligados ficam de fora. Listar, ler e apagar uma thread não existem na API.

Perguntas frequentes

O que é a API Claude Message Threads?

É um recurso beta da API Messages que guarda uma conversa do lado da Anthropic para que os turnos seguintes enviem só mensagens novas. O cabeçalho beta é message-threads-2026-08-12, e cada requisição acrescenta um objeto thread com type em create ou continue.

As threads funcionam com cache de prompt?

Sim. A thread não faz o cache do seu prompt por você: envie um cache_control de nível superior em cada requisição e fique em quatro pontos de quebra. Os pontos em mensagens guardadas ficam fora dessa conta; o de nível superior e os de system ou tools contam.

Posso trocar de modelo no meio de uma thread?

Trocar de modelo exige uma thread nova. model é um campo fixo, então um valor diferente devolve 400 thread_fingerprint_mismatch; comece uma thread nova com a conversa completa e o modelo novo.

Por que um continue devolve 400 sem error_code?

Falta previous_message_id no continue, ou ele inclui system ou tools, mesmo como null. Esses 400 trazem uma message e omitem error_code, então leia o texto.

Quanto tempo uma thread dura e o que acontece quando ela expira?

Uma thread expira 5 minutos depois da última requisição e é apagada no máximo 1 hora depois do último uso. Depois disso, um continue devolve 404 thread_not_found; envie a conversa completa numa nova requisição create e continue a partir do id dela.

Fontes verificadas

• Anthropic: message threads
• Anthropic: cache de prompt
• Anthropic: preços da API Claude
• Anthropic: versões da API