Guía de Claude Message Threads API

La API de message threads de Claude permite enviar una conversación larga una sola vez y, en cada turno posterior, mandar solo los mensajes nuevos (página Message threads de Anthropic, 4 de noviembre de 2026). Añade "thread": {"type": "create"} a la primera petición de Messages y el encabezado beta message-threads-2026-08-12: la API guarda la conversación en memoria y la siguiente petición sube menos contenido.

Es una beta en todos los modelos. Pueden usarla 17 ID de modelo, entre ellos Claude Opus 5.5, que es el que llama el código de abajo. El encabezado beta va en cada petición de un hilo.

Qué ahorra un hilo

Sin hilo, cada turno lleva la transcripción completa: el system prompt, las definiciones de herramientas, todos los mensajes anteriores y todos los resultados de herramientas. Un hilo guarda esa conversación, incluida la respuesta de Claude, bajo el id de la respuesta, y una petición continue envía solo lo ocurrido desde entonces (página Message threads, 4 de noviembre de 2026). Cada turno sube menos.

La caché de prompts ayuda a la misma conversación por otro lado. Un acierto de caché abarata la entrada repetida: en Opus 5.5, 0,20 USD por millón de tokens frente a 4 USD de entrada nueva (página de precios de Anthropic, 4 de noviembre de 2026). Aun así, la petición sigue llevando esa entrada. El hilo reduce lo que envías; la caché reduce el precio de lo que se repite. En sesiones largas conviene usar las dos cosas, y reducir el consumo de tokens de Claude Code cubre la parte del contexto.

Los hilos no cambian el precio ni los límites de velocidad (página Message threads, 4 de noviembre de 2026). Las tarifas actuales están en precios.

La caché la pones tú. Envía un cache_control de nivel superior en cada petición y la API lo aplica al último bloque cacheable de los messages de esa petición. El límite de cuatro puntos de interrupción es una regla de la caché de prompts de toda la plataforma, y la caché automática usa uno de los cuatro (página de caché de prompts de Anthropic, 4 de noviembre de 2026). Reparte así:

1. el cache_control de nivel superior, un punto en cada petición del hilo;
2. uno en system, enviado con la petición create;
3. uno en tools, también en create;
4. uno en el mensaje más reciente.

Los puntos de interrupción de mensajes guardados antes quedan fuera de ese límite, porque una petición continue solo envía mensajes nuevos. Una vez enviado, el punto se queda donde está. Al reenviar una conversación, quita los puntos de los mensajes anteriores y deja uno en el último bloque (página Message threads, 4 de noviembre de 2026).

Crea el primer turno y sigue

Tres pasos:

1. Pon tu clave de Anthropic en ANTHROPIC_API_KEY.
2. Envía la conversación completa, con system y tools si los usas, más "thread": {"type": "create"}.
3. Envía solo los mensajes posteriores a la última respuesta, más "thread": {"type": "continue", "previous_message_id": "<previous id>"}, y deja fuera system y tools.

Cada petición lleva el encabezado beta y anthropic-version: 2026-10-21, la versión actual (página de versiones de Anthropic, 4 de noviembre 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"}
  }'

Guarda el id de esa respuesta. La siguiente petición envía solo el mensaje nuevo:

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

Conserva el id más reciente de cada respuesta: un hilo solo admite añadidos, cada id de respuesta se puede continuar una vez y la siguiente petición debe usar el último (página Message threads, 4 de noviembre de 2026).

Si necesitas otra forma de conseguir una clave de API, OmniaKey vende acceso a la API de Claude con los mismos ID de modelo, así que el cuerpo de la petición no cambia. Los hilos son una beta del lado de Anthropic, así que antes de depender de ellos en producción comprueba que el intermediario que uses pasa el campo thread tal cual.

El SDK de Python guarda los id por ti. Crea un helper con client.beta.messages.thread(...), que solo prepara la llamada, y envía cada turno con thread.send(). El helper añade el encabezado beta, crea en el primer turno, continúa solo con los mensajes nuevos y reenvía la conversación completa una vez en una nueva petición create cuando un continue devuelve thread_not_found, thread_already_continued o thread_continue_in_flight (página Message threads, 4 de noviembre de 2026).

import anthropic

client = anthropic.Anthropic()  # lee ANTHROPIC_API_KEY

# El helper aún no envía nada; guarda los campos que reutiliza cada turno.
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 próxima vez continúa desde este id

No ejecutamos estas peticiones contra la API de Anthropic; la forma de las peticiones viene de la página Message threads de Anthropic. Para streaming, thread.stream(...) con stream.get_final_message() da el mismo flujo, y thread.previous_message_id devuelve el id cuando prefieres llevar la cuenta tú.

Qué reenviar y qué no reenviar nunca

Envía los campos fijos en cada petición con los mismos valores, system y tools solo en la petición create, y deja que los campos libres cambien de un turno a otro.

El 400 por un campo fijo cambiado lleva thread_fingerprint_mismatch y el mensaje lista los campos que difieren. Para cambiar uno de esos valores, empieza un hilo nuevo con la conversación completa y el valor nuevo.

Si omites previous_message_id, el continue devuelve un 400 cuyo cuerpo trae un mensaje pero ningún error_code; incluir system o tools hace lo mismo. Un continue debe llevar exactamente los mensajes posteriores a la última respuesta.

mcp_servers es fijo, pero las URL de los servidores y los tokens de autorización viven solo en tu petición, así que envía la lista en cada petición que use MCP; un token puede cambiar entre peticiones. El id del contenedor también vive solo en tu petición, así que envía container cada vez (página Message threads, 4 de noviembre de 2026).

El fallback del servidor se decide en el create: envía fallbacks en todas las peticiones del hilo o en ninguna. El valor puede cambiar entre turnos, pero añadir o quitar el campo devuelve thread_fingerprint_mismatch.

Caducidad, reenvío y el 404

Un hilo caduca 5 minutos después de su última petición, y la API lo borra como máximo 1 hora después de su último uso. Cada respuesta guardada reinicia los 5 minutos. Los hilos no son aptos para retención cero de datos: la conversación, el system prompt y las herramientas están en memoria, cifrados, y nunca se escriben en almacenamiento duradero (página Message threads, 4 de noviembre de 2026).

Ningún campo de la respuesta dice si la API guardó un turno, ni en un create ni en un continue. Lo sabes en la siguiente petición continue, así que tu aplicación es la fuente de verdad y conserva su propia copia de cada mensaje (página Message threads, 4 de noviembre de 2026).

Cuando un continue devuelve 404 thread_not_found, envía la conversación completa en una nueva petición create y continúa desde el id de esa respuesta. La API da el mismo 404 en todos estos casos:

• el hilo caducó;
• el turno anterior se sirvió y luego se descartó, por ejemplo una llamada a herramienta cortada por max_tokens;
• un modelo de fallback escribió la respuesta anterior;
• la respuesta anterior aún se está generando;
• la petición viene de otra organización, espacio de trabajo, usuario o clave de espacio de trabajo;
• los mensajes nuevos añaden contenido que la conversación guardada no tiene, como la primera imagen de una conversación que no tenía ninguna.

Reenviar la conversación completa siempre es seguro y repara todos esos casos.

El streaming añade una regla: continúa desde el id de la respuesta solo después de message_stop, porque un continue enviado antes puede devolver 404. Si el stream de una petición continue se corta antes de message_stop, envía otra vez la misma petición continue, y reenvía si eso devuelve thread_already_continued o thread_continue_in_flight. El helper del SDK deja el stream cortado para que lo reintentes tú.

Otros tres casos tienen su propio camino:

• pause_turn: continúa desde el id de esa respuesta con "messages": []. Si eso da 404, reenvía incluyendo la respuesta pausada.
• stop_reason: "refusal": empieza un hilo nuevo sin el turno que lo causó; la API puede tener ya el turno rechazado.
• una entrada fallback_message en usage.iterations, o en el message_delta final de un stream, marca una respuesta de fallback: reenvía.

Errores

Los cinco errores de hilo vuelven antes de que se ejecute el modelo: la petición no usa tokens y el hilo conserva su plazo. error.type es invalid_request_error para los 400 y not_found_error para el 404 (página Message threads, 4 de noviembre de 2026).

• 404, thread_not_found: la API no puede continuar este hilo. Envía la conversación completa en una nueva petición create.
• 400, thread_fingerprint_mismatch: un campo fijo cambió respecto al valor guardado con el hilo. Déjalo idéntico o empieza un hilo nuevo.
• 400, thread_already_continued: ese id de respuesta ya se usó una vez. Continúa desde el id más reciente y reenvía si nunca lo recibiste.
• 400, thread_continue_in_flight: otro continue desde el mismo id sigue en marcha, normalmente tu intento anterior. Déjalo terminar o reenvía.
• 400, thread_unsupported_request: la petición usa una función o un ajuste de la organización que los hilos no admiten. error.details.unsupported nombra uno de context_management, cache_control, fallbacks, hipaa o inference_hooks; esa lista puede crecer, así que si un valor te resulta desconocido, envía la conversación completa sin thread.

Message Batches rechaza el campo thread (un elemento de lote que lo lleve falla con invalid_request_error), y el conteo de tokens y la compactación devuelven 400; también la edición de contexto distinta de clear_thinking_20251015 con keep: "all". Las organizaciones listas para HIPAA y las que tienen Inference hooks activados quedan fuera. Listar, leer y borrar un hilo no están disponibles en la API.

Preguntas frecuentes

¿Qué es la API de message threads de Claude?

Es una función beta de la Messages API que guarda una conversación del lado de Anthropic para que los turnos siguientes envíen solo mensajes nuevos. El encabezado beta es message-threads-2026-08-12, y cada petición añade un objeto thread con type en create o continue.

¿Los hilos funcionan con la caché de prompts?

Sí. Un hilo no cachea tu prompt por ti: envía un cache_control de nivel superior en cada petición y no pases de cuatro puntos de interrupción. Los puntos de los mensajes guardados quedan fuera de esa cuenta; el de nivel superior y los de system o tools sí cuentan.

¿Puedo cambiar de modelo a mitad de un hilo?

Cambiar de modelo exige un hilo nuevo. model es un campo fijo, así que un valor distinto devuelve 400 thread_fingerprint_mismatch; empieza un hilo nuevo con la conversación completa y el modelo nuevo.

¿Por qué un continue devuelve 400 sin error_code?

Al continue le falta previous_message_id, o incluye system o tools, aunque sea null. Esos 400 llevan un mensaje y omiten error_code, así que lee el texto.

¿Cuánto dura un hilo y qué pasa cuando caduca?

Un hilo caduca 5 minutos después de su última petición y se borra como máximo 1 hora después de su último uso. Después, un continue devuelve 404 thread_not_found; envía la conversación completa en una nueva petición create y continúa desde su id.

Fuentes consultadas

• Anthropic: message threads
• Anthropic: caché de prompts
• Anthropic: precios de la API de Claude
• Anthropic: versiones de la API