CONCEPT Capture the request-id on every call
When a request behaves oddly and you open a support ticket, the first thing Anthropic asks for is the
request ID. Every API response carries a unique request-id response
header (a value like req_018EeWyXxfu5pfWkrYcMdjWG), and the same identifier appears as the
request_id field inside error response bodies. Log it on both success and
failure — you can't retrieve it after the fact.
| Surface | Where the ID lives | How to read it |
|---|---|---|
| Successful response | request-id header | Python/TS: message._request_id; others: raw-response accessor |
| Error body | request_id JSON field | On the parsed error object |
| Raw headers (any SDK) | request-id | .with_raw_response → headers.get("request-id") |
_request_id property on Python/TS response objects is public despite the
underscore. Include it in every log line so a customer complaint maps to one exact call.CONCEPT Log I/O + latency + tokens, propagate a trace ID
A useful log record is more than the request ID. For each call capture the inputs (model,
prompt/params — redacted as policy requires), the outputs (text, stop_reason),
the latency, and the token usage (8.1). For agents, a single user task fans
out into many API calls and tool invocations — so mint one trace ID at the top of the task and
propagate it across every model call and tool call. That's what lets you reconstruct "what did the
agent do" as a single timeline instead of disconnected log lines.
DIAGRAM One trace ID across an agent's tool calls
(one per run)"] T --> C1["API call 1
trace_id + request-id A"] C1 --> TOOL["Tool call
trace_id propagated"] TOOL --> C2["API call 2
trace_id + request-id B"] C2 --> DONE["Final answer"] C2 -.->|"error?"| ERR["🔴 Log request_id
from error body"] C1 --> LOG["📋 One correlated timeline:
inputs · outputs · latency · tokens"] C2 --> LOG ERR --> LOG classDef ok fill:#d4edda,stroke:#28a745,color:#155724; classDef gate fill:#ffe8cc,stroke:#ff9f40,color:#9a4a0a; classDef bad fill:#f8d7da,stroke:#dc3545,color:#721c24; class DONE ok; class LOG gate; class ERR bad;
CODE A correlated log record per call
Read the request ID from the response, and from the error body when a call throws. One trace_id
threads the whole run.
import time, uuid, anthropic trace_id = uuid.uuid4().hex # mint ONCE at the top of the agent task def call(client, **params): t0 = time.monotonic() try: resp = client.messages.create(**params) log({ "trace_id": trace_id, "request_id": resp._request_id, # from the request-id header "latency_ms": (time.monotonic() - t0) * 1000, "input": params["messages"], "stop_reason": resp.stop_reason, "usage": resp.usage.to_dict(), # tokens (8.1) }) return resp except anthropic.APIStatusError as e: log({"trace_id": trace_id, "request_id": e.request_id, # same id, from the error body "status": e.status_code, "error_type": e.type, "latency_ms": (time.monotonic() - t0) * 1000}) raise
TRADE-OFFS What to put in the log
✅ Structured, ID-rich records
- request-id → Anthropic can trace it end-to-end
- trace-id → whole agent run reconstructs as one timeline
- Redact PII in prompts; keep IDs, latency, tokens
⚠️ Prose logs / no IDs
- Cheap to write, human-readable at a glance
- But: support can't locate the call without a request-id
- Agent runs can't be stitched back together
EXAM TRAPS
request_id is on the error body too — and that's exactly the call you'll need to report.
Log it on failure._request_id is private because of the underscore. → It's a
documented, public property on Python/TS response objects. Other SDKs read the request-id header
via the raw-response accessor.PRACTICE
Q1 · A customer reports a bad response. What's the one field you need to have logged?
The request-id (from the request-id response header, exposed as
_request_id in Python/TS). It lets Anthropic support trace that exact request end-to-end. Without
it, there's no reliable way to locate the call.
Q2 · How do you correlate the 6 API calls an agent made for one user task?
Mint one trace ID at the start of the task and propagate it through every model call and tool call, logging it on each record. Anthropic's request-id is per-call and can't span the run; your trace ID stitches the timeline together.
Q3 · Where do you get the request ID when a call raises an error?
From the error response body — it carries a request_id field (surfaced on
the SDK's typed exception, e.g. e.request_id). Same identifier as the success-path
request-id header.