Skip to main content

Turing Headers Protocol

In addition to standard HTTP headers, the Turing Platform defines a set of X-Turing-* / x-turing-* headers: response headers return the trace ID, actual routing result, and processing time for each call; request headers are used for proactive debugging, tagging, and trace chaining. This page is the authoritative reference for these headers — other pages (Request Tracing, Timeouts, Retries & Fallback) cover usage in their respective contexts, but definitions here take precedence.

Response Headers (Returned by the Platform)​

HeaderDescriptionScope
X-Turing-Trace-IdThe Turing Platform request trace ID, used for log lookup and billing inquiriesEvery response
X-Turing-Process-TimePlatform-side processing time in millisecondsEvery response
x-turing-model-idThe model ID that actually served the request (especially useful with fallback / auto routing)Non-streaming LLM responses
x-turing-retriesThe actual number of retries that occurred for the requestNon-streaming LLM responses
x-turing-fallbacksThe actual number of fallback switches that occurred for the requestNon-streaming LLM responses
X-Turing-Memory-*The Managed Memory read and capture outcome for the turn; six headers, see Managed Memory HeadersChat Completions responses with turing_options.memory enabled, including streaming

A typical non-streaming response:

curl -i $TURING_BASE_URL/chat/completions \
-H "Authorization: Bearer $TURING_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "turing/gpt-4.1",
"messages": [{"role": "user", "content": "Hello!"}]
}'

# Response Headers:
# x-turing-trace-id: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
# x-turing-process-time: 812.34
# x-turing-model-id: gpt-4.1
# x-turing-retries: 0
# x-turing-fallbacks: 0

For the complete workflow of using X-Turing-Trace-Id to debug issues and look up billing records, see Request Tracing.


Response Observability Headers: Actual Model / Retries / Fallbacks​

When fallback / retry is configured, x-turing-model-id / x-turing-retries / x-turing-fallbacks let you confirm on the client side which model actually served the request and how many retries and fallbacks occurred:

HeaderDescription
x-turing-model-idThe model ID that actually served the request. When fallbacks (especially auto) is configured, use this to confirm which model was ultimately used.
x-turing-retriesThe actual number of retries that occurred for the request (corresponding to turing_options.max_retries)
x-turing-fallbacksThe actual number of fallback switches that occurred for the request
from openai import OpenAI

client = OpenAI()

response = client.chat.completions.with_raw_response.create(
model="deepseek-flash",
messages=[{"role": "user", "content": "Hello!"}],
turing_options={
"max_retries": 2,
"fallbacks": "auto",
},
)

print("served by:", response.headers.get("x-turing-model-id"))
print("retries: ", response.headers.get("x-turing-retries"))
print("fallbacks:", response.headers.get("x-turing-fallbacks"))

completion = response.parse()
info
  • Non-streaming only: Streaming responses (stream=True) are delivered as SSE chunks and do not carry these three headers.
  • Also present on error responses: When all fallbacks are exhausted and an error is returned, these three headers are still included — which is precisely when you need them most to determine how far the chain progressed.
  • Browser-accessible: All three headers are included in the CORS expose_headers list, so frontend code can read them directly via response.headers.get(...).

For configuration options (max_retries / fallbacks), see Timeouts, Retries & Fallback.


Managed Memory Headers​

When a Chat Completions request enables turing_options.memory, the response carries the headers below to show whether memory was used and captured for the turn. Response bodies and SSE events keep their format, so clients that ignore these headers are unaffected. To enable Managed Memory, see LTM integrations.

HeaderDescription
X-Turing-Memory-Read-Statusused: memory was used for this turn; empty: no relevant memory exists, which is normal; degraded: memory was not used, and the answer is still returned; skipped: the request turned reading off (recall: false), so nothing was recalled
X-Turing-Memory-Capture-Statusaccepted: the turn was written as an Event and memory is derived asynchronously; skipped: the turn is not written; failed: the write did not succeed; conflict: the same turn was already written with different content, or the user's memory is being erased, so nothing was written; pending: a streaming response whose write happens after the output ends
X-Turing-Memory-Event-IdThe written Event ID, returned only with accepted
X-Turing-Memory-Turn-IdThe memory turn ID, returned whenever Managed Memory ran for the turn, including turns with reading off
X-Turing-Memory-Evidence-SourceThe memory evidence source, returned when a memory read ran; currently always computed; absent when reading is off
X-Turing-Memory-ReasonA reason code when memory was not used or the turn was not written, for example fallback_enabled (the request configures fallbacks, so memory is bypassed for the whole request), ltm_unavailable (the memory read or write could not complete), caller_tool_call (the model returned a tool call, so the turn is not written), or capture_disabled (the request turned writing off with capture: false). Other values are for troubleshooting; record them verbatim
info
  • Only three kinds of error fail the request: an invalid turing_options.memory (code 1004, including recall and capture both false), a credential that may not use this client's memory (code 1308), and a Space that does not exist or does not belong to the current client and environment (code 1751). Other memory failures do not interrupt the answer and only appear in the headers above; monitor degraded, failed, and X-Turing-Memory-Reason.
  • A degraded read still writes the turn: when the read degrades because LTM is temporarily unavailable (X-Turing-Memory-Read-Status is degraded with the reason ltm_unavailable), the answer is returned as usual and the turn is still written; X-Turing-Memory-Capture-Status carries the result of the write.
  • Streaming responses carry them too: the headers are sent before the output starts, before anything is written, so X-Turing-Memory-Capture-Status is pending (skipped when writing is off or memory is bypassed).
  • Browser-accessible: all of these headers are in the CORS expose_headers list.

For what each error code means, see Error Code Reference.


Request Headers (Set by the Client)​

HeaderDescription
AuthorizationBearer <API_KEY> — required for all requests
X-Client-Request-IdA request ID generated by the client. Can still be used for debugging when a request fails or receives no response (see Request Tracing)
X-Turing-TagsRequest tags as a JSON string. Used for usage categorization and source identification
X-Turing-Trace-Id(Optional) Pass this proactively to reuse a trace ID and link multiple calls within the same business flow under a single ID. Only valid within a 10-minute freshness window; expired IDs are ignored and a new one is generated automatically
import json
from openai import OpenAI

client = OpenAI()

completion = client.chat.completions.create(
model="turing/gpt-4.1",
messages=[{"role": "user", "content": "Hello!"}],
extra_headers={
"X-Client-Request-Id": "req-20260715-abcdef",
"X-Turing-Tags": json.dumps({"team": "growth", "scene": "summarizer"}),
},
)

See also​

Self-check