# Claude Message Threads API: guia de threads

> As threads da API Claude: cabeçalho beta, requisições create e continue, os campos que você precisa reenviar, a expiração e o caminho do 404.

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

---

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

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

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

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

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

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

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

|Grupo|Campos|Regra|
|-|-|-|
|Só create|`system`, `tools`|Só na requisição create; enviar qualquer um dos dois numa requisição continue, mesmo como `null`, dá 400.|
|Fixos|`model`, `tool_choice`, `thinking`, `mcp_servers` menos o token de autorização de cada servidor, `context_management`, `output_config`, os `skills` de `container`, o `cache_control` de nível superior e o conjunto de valores de `anthropic-beta`|Sempre o mesmo valor. Um valor diferente devolve 400 e nomeia o campo que difere.|
|Livres|`max_tokens`, `stop_sequences`, `stream`, `metadata`, `service_tier` e os campos sem nome|Mude quando quiser.|

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](https://platform.claude.com/docs/en/build-with-claude/message-threads)
- [Anthropic: cache de prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [Anthropic: preços da API Claude](https://platform.claude.com/docs/en/about-claude/pricing)
- [Anthropic: versões da API](https://platform.claude.com/docs/en/api/versioning)