> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudhumans.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a message's execution trace > The execution tree behind one processed message: the agent hand-offs, tool calls, generations and routing decision that produced it, with per-step timing and status. Take `messageId` and `conversationId` from getConversationSummary's message list — a response message's own id resolves it directly; a customer message's id also resolves the same trace, as a fallback. Prompt and generation CONTENTS (the assembled system prompt, tool payloads, model completions) and section content are never included — resolve a section's text with `getEntry`. The response also carries `modelDecision`, ClaudIA's persisted record of what the model saw and used: the sections retrieval brought (with score and selection flags), the ids it declared it used, the classifier's routing (RESPOND/CLARIFY/NO_VALID_CONTENT) and the written reasoning, including the routing judge's. ## OpenAPI ````yaml api-reference/specs/claudia/v1.json GET /v1/messages/{messageId}/trace openapi: 3.0.1 info: title: Claudia API version: 1.0.0 servers: - url: https://api.cloudhumans.com/claudia description: Production - url: https://api.cloudhumans.com/claudia/staging description: Staging security: - bearerAuth: [] tags: - name: MCP Servers description: >- The MCP servers your agents can call tools on. Registering one here is what makes its tools selectable in an agent; the credentials it needs are stored encrypted and never read back. - name: Knowledge Base Content description: Read, search and edit the content that answers your customers. - name: Content Quality description: Rewrites proposed for content that is answering your customers badly. - name: Playground description: >- Talk to one of your agents as if you were a customer, without touching a real conversation. - name: Project Settings description: >- Read and change how a ClaudIA project behaves — the settings screens of the ClaudIA app, as an API. - name: Content Improvements description: Answers Claudia proposes for questions your content does not cover yet. - name: Knowledge Bases description: The knowledge bases your account can manage. - name: Content Sources description: The sites Claudia crawls to keep a knowledge base in sync. - name: Agents description: >- The AI agents (assistants) configured for your tenant: the orchestrator (supervisor) and its specialists (react). Reads answer the same passthrough shape the platform stores; creates land as DRAFTS a human reviews and publishes in the app. - name: Agent Tools description: >- The tool catalog your agents can be given, aggregated across every MCP server registered for the tenant. This is the same catalog an assistant's mcp_servers[].tools whitelist is validated against. - name: Conversations description: >- Read access to a conversation's lean investigation summary — messages, status and resolution — and the execution trace behind one of its processed messages, without the internal processing state the hub UI's full read carries. paths: /v1/messages/{messageId}/trace: get: tags: - Conversations summary: Get a message's execution trace description: >- The execution tree behind one processed message: the agent hand-offs, tool calls, generations and routing decision that produced it, with per-step timing and status. Take `messageId` and `conversationId` from getConversationSummary's message list — a response message's own id resolves it directly; a customer message's id also resolves the same trace, as a fallback. Prompt and generation CONTENTS (the assembled system prompt, tool payloads, model completions) and section content are never included — resolve a section's text with `getEntry`. The response also carries `modelDecision`, ClaudIA's persisted record of what the model saw and used: the sections retrieval brought (with score and selection flags), the ids it declared it used, the classifier's routing (RESPOND/CLARIFY/NO_VALID_CONTENT) and the written reasoning, including the routing judge's. operationId: getMessageTrace parameters: - name: messageId in: path description: The message id, from getConversationSummary's message list. required: true schema: type: string - name: conversationId in: query description: The conversation this message belongs to. required: true schema: type: string responses: '200': description: >- The trace, lean-projected. `trace` is absent when Langfuse has not ingested it yet for this message — retry shortly, this is not an error. content: application/json: schema: $ref: '#/components/schemas/MessageTrace' '400': description: The request could not be answered as written. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, expired or invalid credentials. '403': description: The credentials hold no account allowed to manage this content. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- No conversation reachable with your credentials matches `conversationId`. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limit applied by the API gateway. Back off and retry. '500': description: Something went wrong resolving the trace. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: The trace backend could not be reached. Retrying is reasonable. content: application/json: schema: $ref: '#/components/schemas/Error' '504': description: >- The trace lookup did not finish within its budget. Retrying is reasonable. content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: MessageTrace: type: object required: - messageId - projectName - conversationId - assistants properties: messageId: type: string description: >- The message this trace was resolved for — from getConversationSummary's message list. example: 6683f1c2a4b19e0012ab34cd projectName: type: string description: The ClaudIA project this trace belongs to. example: acme_support conversationId: type: string description: >- The conversation this message belongs to — the same id you passed as `conversationId`. example: 3f1c8a52-1c4e-4d0a-9a1b-2f6de2a3c111 trace: nullable: true allOf: - $ref: '#/components/schemas/MessageTraceDetails' description: >- The trace itself. Absent when Langfuse has not ingested it yet for this message — retry shortly, this is not an error. judge: nullable: true allOf: - $ref: '#/components/schemas/MessageTraceJudge' description: >- The routing judge's validated decision for this message. Absent when the trace has no judge observation — a non-agentic path, or a trace predating this instrumentation. assistants: type: object description: >- Directory of the agents that ran, keyed by `assistant_id`/`agent_id`, so an observation's `metadata.assistant_id` can be resolved to a display name and role. Empty when there is no trace yet, or the directory could not be resolved. additionalProperties: $ref: '#/components/schemas/MessageTraceAssistant' modelDecision: nullable: true allOf: - $ref: '#/components/schemas/MessageTraceModelDecision' description: >- What the model saw and used to produce this reply: the sections retrieved (with score and selection flags), the ids it declared it used, the classifier's routing, and the model's own written reasoning. Read from ClaudIA's persisted decision record, independent of the Langfuse trace — it can be present when `trace` is still absent. Absent for a message that has no decision record (e.g. a customer turn, or a reply the platform did not audit). description: >- The execution tree behind one processed message — steps, agent hand-offs, tool calls, routing decision, timing and errors — plus the model's persisted decision record (`modelDecision`): the sections it saw and used, the classifier routing, and the written reasoning. A LEAN projection: prompt/generation CONTENTS and section CONTENT are never included. Error: required: - error type: object properties: error: type: string description: What went wrong. example: 'Forbidden: token holds no claim for the requested account' description: Something the caller needs to fix. MessageTraceDetails: type: object required: - id - observations properties: id: type: string description: Langfuse's own id for this trace. example: deadbeef name: type: string description: Trace name. example: message-processing timestamp: type: string description: When the trace started (ISO-8601). example: '2026-06-10T12:00:00Z' observations: type: array description: >- The execution tree, oldest first: every step, agent hand-off, tool call and generation that ran for this message. Prompt and completion CONTENTS are not included — only the step skeleton, timing and status. items: $ref: '#/components/schemas/MessageTraceObservation' description: >- The Langfuse trace's own identity and timing. NOT its `url` — a direct link into the Langfuse project is not part of this public contract. MessageTraceJudge: type: object properties: action: type: string description: >- The validated routing action actually taken: `CONTINUE` or `STOP`. Authoritative — an out-of-list/hallucinated pick correctly reports `STOP` here even though `selectedAgent` still shows the raw (invalid) pick. example: CONTINUE selectedAgent: type: string description: The model's raw agent pick, surfaced even when invalid. example: billing_agent selectedAgentId: type: string description: The model's raw agent id pick, surfaced even when invalid. example: agent-7 fallbackReason: type: string description: >- Why `action` is `STOP` despite a non-null `selectedAgent`: `stop_sentinel` or `out_of_list`. Absent when a valid agent was selected (no fallback). example: out_of_list hallucinated: type: boolean description: >- True when the raw pick named an agent outside the project's valid agent list. example: false reasoning: type: string description: >- The judge's written justification for its routing decision. Absent when the trace predates this instrumentation or the judge wrote none. example: The customer asked about an invoice, so I am routing to billing. description: >- The routing judge's VALIDATED decision for this message — which agent it routed to, or why it stopped — and its written reasoning for the decision. MessageTraceAssistant: type: object required: - name - role properties: name: type: string description: Display name. example: Billing role: type: string description: '`supervisor` or `sub_agent`.' example: sub_agent description: >- One agent that can appear in the trace: its display name and its role in the supervisor graph. MessageTraceModelDecision: type: object required: - usedSectionIds - relevantSectionIds - sections properties: responseType: type: string description: >- The kind of reply that was persisted, e.g. `AcceptableConfidenceResponse`, `ClarificationResponse`, `NoValidContentResponse`, `AgenticResponse`. Absent on legacy records. example: ClarificationResponse agentAction: type: string description: >- The action ClaudIA took with the reply: `NO_ACTION`, `FORWARD_N2` or one of its variants (`FORWARD_N2_FORCED`, `FORWARD_N2_DETECT_TRANSFER`, `FORWARD_N2_BY_UNANSWERED_TICKET_ESCALATOR` — all handed to a human), `RESOLVE_TICKET` or `CLOSE_TICKET`. Absent on legacy records. example: NO_ACTION classifierAction: type: string description: >- The classifier's routing for this turn: `RESPOND` (answer with content), `CLARIFY` (ask the customer for detail) or `NO_VALID_CONTENT` (no section covers the question). Absent when the classification step did not run for this reply. example: CLARIFY modelReasoning: type: string description: >- The model's own written justification for the reply — why it used or discarded each section, referencing them by id. Absent when the model wrote none. example: >- Usei a seção sec-1 porque cobre a pergunta sobre boleto; descartei sec-2 por tratar de cartão. classificationReasoning: type: string description: >- The classifier's written justification for its routing. Absent when the classification step did not run or wrote none. example: Duas seções competem pela intenção do cliente. clarificationReasoning: type: string description: >- Why the model chose to ask for clarification. Only present on a clarification reply. example: A pergunta é ambígua entre boleto e cartão. noValidContentReasoning: type: string description: >- Why the model concluded no available content answers the question. Only present on a no-valid-content reply. example: Nenhuma seção cobre segunda via de boleto. usedSectionIds: type: array description: >- Ids of the sections the model declared it used in the reply. Empty when it declared none. Cross-reference with `sections[].usedInResponse`. items: type: string relevantSectionIds: type: array description: >- Ids the model flagged as relevant for the routing it chose — the candidates behind a clarification, or the near-misses behind a no-valid-content. Empty when the reply carries no such list. items: type: string sections: type: array description: >- Every section retrieval brought for this turn, with score and selection flags — including the ones the model did NOT use, which is what distinguishes 'search did not find it' from 'the model chose not to use it'. items: $ref: '#/components/schemas/MessageTraceSection' description: >- ClaudIA's persisted decision record for one reply: which sections the retrieval brought, which the classifier selected or discarded, which the model declared it used, and the reasoning it wrote for the choice. Section CONTENT is not included — resolve a section's text with `getEntry` using its id. MessageTraceObservation: type: object required: - id properties: id: type: string description: Identifies this node. example: obs-root name: type: string description: >- The node's name, e.g. `AGENTIC_REACT_AGENT`, `OPENAI`, or a tool ref. example: AGENTIC_REACT_AGENT type: type: string description: 'The node''s kind: `SPAN`, `GENERATION`, `TOOL`, or `EVENT`.' example: SPAN parentObservationId: type: string description: >- The parent node's id — walk these to reconstruct the supervisor→sub-agent tree. Absent for a root node. example: obs-root startTime: type: string description: When the node started (ISO-8601). example: '2026-06-10T12:00:00Z' endTime: type: string description: >- When the node ended (ISO-8601). Absent while it was still running when the trace was captured. example: '2026-06-10T12:00:01Z' status: type: string description: >- How the node finished: `ok`, `warn`, `error`, or `debug`. Absent when Langfuse recorded no status for it. example: ok statusMessage: type: string description: Error or warning detail, present when `status` is not `ok`. example: tool timeout metadata: type: object additionalProperties: true description: >- A curated subset of the node's metadata — only `assistant_id`, `checkpoint_ns`, `langgraph_checkpoint_ns` and `graph_id`, the keys needed to resolve which agent ran this step. A key the node did not carry is simply absent from the map, never null. description: >- One node of the execution tree — a step span, a tool call, or a model generation. NOT its `input`/`output`: those carry the assembled system prompt, tool payloads and model completions, which are not part of this public contract. MessageTraceSection: type: object required: - id - usedInResponse properties: id: type: string description: The section's id — resolvable with `getEntry`. example: 665f1c2a4b19e0012ab34c99 title: type: string description: The section's title. Absent on legacy records. example: Como pagar boleto score: type: number description: Retrieval similarity score for this turn. Absent on legacy records. example: 0.91 type: type: string description: 'Section type: `N1`, `N2` or `INTERACTIVE`. Absent on legacy records.' example: N1 tag: type: string description: The section's tag, when it carries one. example: faq topic: type: string description: The section's topic, when it carries one. example: pagamentos wasSelected: type: boolean description: >- Whether the classifier selected (`true`) or discarded (`false`) this section. Absent when the classification step did not run for this turn. example: true usedInResponse: type: boolean description: Whether the model declared it used this section in the final reply. example: true description: >- One section retrieval brought for the turn — identity, ranking and selection flags only, never its content. Resolve the text with `getEntry` using `id`. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT ````