---
title: "Get Trace config for an agent (or the org default)"
method: GET
path: "/v1/trace/config"
tags: ["Trace"]
---

# Get Trace config for an agent (or the org default)

`GET /v1/trace/config`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/trace/config`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Returns the per-agent Trace config (spec §5.1). Pass `agent_id` to read a specific
agent's config; omit it for the org-wide default a new agent inherits. When nothing
has been configured yet, returns the safe default (`enabled:false`, `mode:warn`,
`fail_open:true`). Requires the `trace:configure` scope.

## Query parameters

- `agent_id` string

## Response `200`

Trace config

- TraceConfig
  - `object` string
  - `agent_id` string, nullable
  - `enabled` boolean
  - `mode` 'warn' | 'modify' | 'block' | 'human_handoff'
  - `etag` string: Content hash the models-side gate pins (version-pinned, ETag-cached pull).
  - `updated_at` integer: Unix ms.
  - `config` TraceConfigInput: Per-agent Trace config (spec §5.1). May be wrapped as { agent_id, config } or sent raw.
    - `agent_id` string: Agent to configure; omit for the org-wide default.
    - `enabled` boolean
    - `channels` string[]
    - `rule_packs` object: Map of pack_id → { enabled, version }, e.g. { tcpa: { enabled: true } }.
    - `guardrails` TraceGuardrails: Inline guardrails compiled into a synthesized rule pack (spec §5.1).
      - `mode` 'warn' | 'modify' | 'block' | 'human_handoff': warn = log only (never blocks); modify = redact/inject; block = suppress; human_handoff = escalate.
      - `block_pii` object
        - `patterns` string[]: Deterministically-redactable PII (context-dependent PII like DOB is Tier-2, not inline).
      - `mandatory_disclosures` object[]
        - `text` string, required: Phrase the agent must speak, e.g. an AI / recording disclosure.
        - `trigger` 'call_start' | 'any': call_start = must appear on the first agent turn.
        - `required_within_seconds` number: Deadline in seconds; otherwise a 2-turn default applies.
      - `blocked_phrases` string[]: Phrases the agent must never say.
      - `fail_open` boolean: Trace down must never make a call worse, log 'unavailable' instead of blocking.
      - `inline_timeout_ms` number: Inline budget; the in-process gate is ~14µs p99, far under this.

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)
- `403`: Key lacks the required scope or the origin is not allow-listed (`code: forbidden | origin_not_allowed`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/819d8e7c4d09?raw)