> ## Documentation Index > Fetch the complete documentation index at: https://docs.trulayer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get the remediation chain for a trace > Returns the chain of control actions for the trace ordered oldest-first. For `retry` actions the per-action TRU-363 diff is inlined under `diff`. For other action types (`fallback_model`, `prompt_modification`, `escalate`) `diff` is null because no remediated span is materialised on the trace. `intended_action_type` is set when the executor's budget gate (TRU-371) auto-converted a retry to escalate. TRU-373. Dashboard-only — requires a Clerk session. Plan-gated to Team+ (Starter/Pro tenants receive HTTP 402 `plan_upgrade_required`). The data surface mirrors `GET /v1/control/actions/:id/diff` and inherits the same gate. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/traces/{id}/remediations openapi: 3.1.0 info: title: TruLayer API version: 0.1.0 description: | Trace ingestion, evaluation, query, and feedback API for TruLayer AI. ### Authentication Two auth schemes coexist: SDK API keys (`Authorization: Bearer tl_...`) and Clerk session JWTs (dashboard). Routes marked "requires Clerk auth" in their summary are unreachable via API key. ### Roles (TRU-234) Dashboard requests carry one of three organization roles: `owner`, `member`, `viewer`. Endpoints enforce role allowlists, not rank comparisons. See `docs/security.md` for the full role-permission matrix. - **owner** — full control including billing, member management, destructive deletes on failure-rules/model-routes/webhooks/eval-rules, control-loop execution, and DLQ resolution. - **member** — read + write (ingest, feedback, evals, API keys, projects, failure-rules, model-routes, webhooks). - **viewer** — read-only dashboard access plus compliance read access to `/v1/audit-log` and `/v1/dlq`. servers: - url: https://api.trulayer.ai description: Production - url: http://localhost:8080 description: Local development security: - BearerAuth: [] tags: - name: health - name: ingest - name: traces - name: metrics - name: feedback - name: evals - name: eval-rules - name: control - name: apikeys - name: model-routes - name: datasets - name: search - name: anomaly - name: webhooks - name: failure-rules - name: eval-runs - name: ci - name: otlp - name: billing - name: deprecations - name: audit - name: failures - name: projects - name: compliance - name: dsr - name: policies - name: members paths: /v1/traces/{id}/remediations: get: tags: - traces summary: Get the remediation chain for a trace description: | Returns the chain of control actions for the trace ordered oldest-first. For `retry` actions the per-action TRU-363 diff is inlined under `diff`. For other action types (`fallback_model`, `prompt_modification`, `escalate`) `diff` is null because no remediated span is materialised on the trace. `intended_action_type` is set when the executor's budget gate (TRU-371) auto-converted a retry to escalate. TRU-373. Dashboard-only — requires a Clerk session. Plan-gated to Team+ (Starter/Pro tenants receive HTTP 402 `plan_upgrade_required`). The data surface mirrors `GET /v1/control/actions/:id/diff` and inherits the same gate. operationId: getTraceRemediations parameters: - name: id in: path required: true schema: type: string format: uuid responses: '200': description: Chain of remediation steps content: application/json: schema: $ref: '#/components/schemas/TraceRemediationsResponse' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' components: schemas: TraceRemediationsResponse: type: object required: - steps properties: steps: type: array items: $ref: '#/components/schemas/TraceRemediationStep' TraceRemediationStep: type: object description: One step in a per-trace remediation chain. TRU-373. required: - action_id - action_type - status - created_at properties: action_id: type: string format: uuid action_type: type: string enum: - retry - fallback_model - prompt_modification - agent_action - escalate status: type: string enum: - pending - pending_approval - executed - failed intended_action_type: type: string nullable: true description: | Set when the executor's budget gate (TRU-371) auto-converted the requested action — typically `retry` becoming `escalate` after the per-trace retry cap was exceeded. created_at: type: string format: date-time diff: $ref: '#/components/schemas/RemediationDiff' ErrorResponse: type: object required: - error properties: error: type: string RemediationDiff: type: object description: | Per-trace remediation diff for a `retry` control action. Lazy- computed on first GET and cached. `embedding_similarity` is a 0..1 score from a Claude similarity rating, with the sentinel `-1.0` when the rater call failed. TRU-363. required: - action_id - original_span_id - remediated_span_id - token_length_delta - latency_delta_ms - embedding_similarity - score_deltas - summary properties: action_id: type: string format: uuid original_span_id: type: string format: uuid remediated_span_id: type: string format: uuid token_length_delta: type: integer description: remediated_tokens - original_tokens (sum of prompt + completion). latency_delta_ms: type: integer format: int64 description: remediated_latency_ms - original_latency_ms. embedding_similarity: type: number format: double description: 0..1 similarity, or -1.0 when the rater call failed. score_deltas: type: array items: $ref: '#/components/schemas/ScoreDelta' summary: type: string citation_density_delta: type: number format: double nullable: true description: | citations_per_1k_chars(remediated) - citations_per_1k_chars(original). Null for diffs computed before TRU-373 (column nullable, no backfill) and when both outputs are empty. TRU-373. ScoreDelta: type: object required: - eval_rule_id - rule_name - original_score - remediated_score - delta properties: eval_rule_id: type: string format: uuid rule_name: type: string original_score: type: number format: double remediated_score: type: number format: double delta: type: number format: double responses: Unauthorized: description: Missing or invalid credentials content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' securitySchemes: BearerAuth: type: http scheme: bearer description: SDK API key (`tl_...`) or Clerk session JWT ````