> ## Documentation Index > Fetch the complete documentation index at: https://docs.decimal.ai/llms.txt > Use this file to discover all available pages before exploring further. # List traces > List traces for the project (paginated). Workspace-scoped: filters by workspace_id when available. When target_manifest_id is provided: - Traces are filtered to only those that existed during the target manifest's active period (between its created_at and the next manifest's created_at). - Each trace is enriched with a `compat` object showing its compatibility against that manifest, computed on-demand if not already cached. Multi-agent filters: - child_agent_name: find parent traces where a child agent matches this name - child_status: further filter those children by status (e.g., 'error') ## OpenAPI ````yaml /openapi.json get /api/v1/traces openapi: 3.1.0 info: title: DecimalAI Platform description: Agent Dataset Lifecycle Platform — Backend API version: 0.1.0 servers: [] security: - BearerAuth: [] tags: - name: traces description: >- Ingest, search, and inspect agent execution traces. A trace is the atomic unit of the platform — every other feature (evaluation, compatibility scoring, dataset building) operates on traces. Each trace is auto-tagged with the manifest hash of the agent that produced it. - name: eval-scores description: >- Push, fetch, and aggregate per-trace evaluation scores. Scores carry source provenance (built-in, DeepEval, LangSmith, custom) and feed the unified decision engine, which produces a keep / repair / replay / drop verdict per trace. - name: skills description: >- Manage reusable instruction blocks (SKILL.md files) that modify agent behavior. Skills are first-class manifest components — changes to a skill appear in your regression-check impact reports. Use these endpoints to create, version, fork, and sync skills with your local SKILL.md files. - name: manifests description: >- Register and inspect manifest versions. A manifest is a snapshot of your agent's structural identity (tools, prompts, models, skills) at a point in time. The SDK registers manifests automatically; these endpoints expose the underlying records. - name: datasets description: >- Build versioned SFT/DPO training datasets from manifest-classified, eval-scored traces. Datasets are reproducible — each version locks the manifest and filter set used to build it. Export as JSONL, Parquet, or push to HuggingFace Hub. - name: replay description: >- Re-execute historical traces against a new manifest version. Replay is the deferred-future capability for behavioral verification of agent changes. The SDK creates a replay batch, your worker executes each task, then submits results back here for eval scoring. - name: registry description: >- Browse and install community skills from the public skills registry. Each registry skill carries a SkillScore — an evidence-tiered quality composite computed from real-world evals, benchmarks, and ratings across organizations. Installing creates a fork in your org — edits don't affect the public version. - name: agents description: >- List and inspect agents, plus their multi-agent topology (orchestrator → sub-agent edges discovered from traces). Agents are identified by a stable agent_name string set in your SDK init() call. - name: import description: >- Bulk-import historical traces from another observability platform or a JSONL backup. Useful for migrating from LangSmith / Braintrust / Langfuse. Duplicate trace IDs are silently skipped — re-running an import is safe. paths: /api/v1/traces: get: tags: - traces summary: List traces description: >- List traces for the project (paginated). Workspace-scoped: filters by workspace_id when available. When target_manifest_id is provided: - Traces are filtered to only those that existed during the target manifest's active period (between its created_at and the next manifest's created_at). - Each trace is enriched with a `compat` object showing its compatibility against that manifest, computed on-demand if not already cached. Multi-agent filters: - child_agent_name: find parent traces where a child agent matches this name - child_status: further filter those children by status (e.g., 'error') operationId: list_traces_api_v1_traces_get parameters: - name: limit in: query required: false schema: type: integer maximum: 100 minimum: 1 default: 20 title: Limit - name: offset in: query required: false schema: type: integer minimum: 0 default: 0 title: Offset - name: status in: query required: false schema: anyOf: - enum: - success - error - degraded type: string - type: 'null' description: 'Filter by trace status. Allowed: success/error/degraded.' title: Status description: 'Filter by trace status. Allowed: success/error/degraded.' - name: agent_name in: query required: false schema: anyOf: - type: string - type: 'null' title: Agent Name - name: eval_verdict in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter by eval verdict (pass/fail/keep/drop/review/...), or 'unevaluated' for traces with no verdict yet. title: Eval Verdict description: >- Filter by eval verdict (pass/fail/keep/drop/review/...), or 'unevaluated' for traces with no verdict yet. - name: source_type in: query required: false schema: anyOf: - enum: - production - test - evaluation - sdk - manual - synthetic - development - sandbox - distillation - snapshot - file - url - eval_replay - sample - demo type: string - type: 'null' description: >- Filter by trace source_type. See ingest allowlist for valid values. title: Source Type description: Filter by trace source_type. See ingest allowlist for valid values. - name: manifest_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Manifest Id - name: search in: query required: false schema: anyOf: - type: string - type: 'null' description: Full-text search across user_input, final_output, and agent_name title: Search description: Full-text search across user_input, final_output, and agent_name - name: include_fixtures in: query required: false schema: type: boolean description: >- When false, drop platform-harness fixture agents (\_\_*, live-*, cuj*, soak-*, …) from the listing — the UI's default. Defaults to true for SDK/API back-compat. Ignored when an explicit agent/skill/tool filter is set (asking by name always works). default: true title: Include Fixtures description: >- When false, drop platform-harness fixture agents (\_\_*, live-*, cuj*, soak-*, …) from the listing — the UI's default. Defaults to true for SDK/API back-compat. Ignored when an explicit agent/skill/tool filter is set (asking by name always works). - name: target_manifest_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Show compatibility of traces relative to this manifest title: Target Manifest Id description: Show compatibility of traces relative to this manifest - name: child_agent_name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter parent traces by child agent name (multi-agent) title: Child Agent Name description: Filter parent traces by child agent name (multi-agent) - name: child_status in: query required: false schema: anyOf: - enum: - success - error - degraded type: string - type: 'null' description: >- Filter child agent matches by status. Allowed: success/error/degraded (H1091). title: Child Status description: >- Filter child agent matches by status. Allowed: success/error/degraded (H1091). - name: tool_name in: query required: false schema: anyOf: - type: string - type: 'null' description: Filter to traces that invoked the named tool (uses ToolCallIndex) title: Tool Name description: Filter to traces that invoked the named tool (uses ToolCallIndex) - name: skill_name in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to traces where the named skill was activated (uses trace_skill_activation). Backs the owner skill-detail live-traces panel (improve#1413). title: Skill Name description: >- Filter to traces where the named skill was activated (uses trace_skill_activation). Backs the owner skill-detail live-traces panel (improve#1413). - name: has_spans in: query required: false schema: anyOf: - type: boolean - type: 'null' description: >- H1336 (improve#702): when true, exclude traces with 0 spans (filters out empty SDK / Hello-World traces that pollute investigation views — caught by cuj07 security-sleuth at #701). When false, only return empty-span traces. Omit for both. title: Has Spans description: >- H1336 (improve#702): when true, exclude traces with 0 spans (filters out empty SDK / Hello-World traces that pollute investigation views — caught by cuj07 security-sleuth at #701). When false, only return empty-span traces. Omit for both. - name: has_llm_calls in: query required: false schema: anyOf: - type: boolean - type: 'null' description: 'H1336 (improve#702): symmetric filter for traces with 0 LLM calls.' title: Has Llm Calls description: 'H1336 (improve#702): symmetric filter for traces with 0 LLM calls.' - name: sort in: query required: false schema: anyOf: - enum: - '-created_at' - created_at - '-started_at' - started_at type: string - type: 'null' description: >- H1092 (improve#843): order results by the given field. Prefix '-' for descending. Defaults to '-created_at'. Unknown values 422 instead of being silently ignored. title: Sort description: >- H1092 (improve#843): order results by the given field. Prefix '-' for descending. Defaults to '-created_at'. Unknown values 422 instead of being silently ignored. - name: started_at_from in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- H1093 (improve#863): inclusive lower bound on RunTrace.started_at (ISO 8601). Malformed dates 422 via Pydantic typing instead of being silently ignored. title: Started At From description: >- H1093 (improve#863): inclusive lower bound on RunTrace.started_at (ISO 8601). Malformed dates 422 via Pydantic typing instead of being silently ignored. - name: started_at_to in: query required: false schema: anyOf: - type: string format: date-time - type: 'null' description: >- H1093 (improve#863): inclusive upper bound on RunTrace.started_at (ISO 8601). Same validation behavior as started_at_from. title: Started At To description: >- H1093 (improve#863): inclusive upper bound on RunTrace.started_at (ISO 8601). Same validation behavior as started_at_from. - name: compat_status in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Filter to traces with this compatibility verdict against `target_manifest_id`. Values: keep / repair / replay / drop. Requires target_manifest_id to be set for authoritative scoping; otherwise falls back to RunTrace.compat_status (a less-precise denormalized field). title: Compat Status description: >- Filter to traces with this compatibility verdict against `target_manifest_id`. Values: keep / repair / replay / drop. Requires target_manifest_id to be set for authoritative scoping; otherwise falls back to RunTrace.compat_status (a less-precise denormalized field). - name: Authorization in: header required: false schema: type: string title: Authorization - name: X-Workspace-Id in: header required: false schema: anyOf: - type: string - type: 'null' title: X-Workspace-Id - name: decimal_session in: cookie required: false schema: anyOf: - type: string - type: 'null' title: Decimal Session responses: '200': description: Successful Response content: application/json: schema: type: object additionalProperties: true title: Response List Traces Api V1 Traces Get example: traces: - id: trc_abc123 agent_name: travel-planner status: success user_input: Find flights to Tokyo final_output: I found 3 flights... manifest_id: mfst_001 eval_verdict: keep eval_score: 0.92 duration_ms: 1240 total_tokens: 850 started_at: '2026-05-10T14:22:00Z' total: 1250 limit: 20 offset: 0 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: Python label: Python SDK source: |- import httpx # Search is performed via query parameters on this endpoint. resp = httpx.get( "https://api.decimal.ai/api/v1/traces", headers={"Authorization": "Bearer dai_sk_..."}, params={"agent_name": "my-agent", "eval_verdict": "drop", "limit": 20}, ) resp.raise_for_status() for t in resp.json()["traces"]: print(t["id"], t["eval_score"]) - lang: Bash label: CLI source: decimalai traces list --agent-name my-agent --limit 20 components: schemas: HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError securitySchemes: BearerAuth: type: http scheme: bearer description: Enter your API key (e.g. dai_sk_test_key_001) ````