---
title: "Trace Ingestion"
method: POST
path: "/v1/traces"
tags: ["Tracing"]
---

# Trace Ingestion

`POST /v1/traces`

## Request

- Base URL: `https://api.confident-ai.com`
- URL: `https://api.confident-ai.com/v1/traces`
- Auth: none declared
- TypeScript: <https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/docs/v1/traces/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new trace on Confident AI.

## Request body

- Trace
  - `uuid` string, required: This is the unique identifier of the trace.
  - `name` string: This is the name of the trace.
  - `input` string: This is the input to the trace.
  - `output` string: This is the output of the trace.
  - `startTime` string, date-time, required: This is the time the trace started.
  - `endTime` string, date-time, required: This is the time the trace ended.
  - `environment` 'production' | 'development' | 'staging' | 'testing': This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform.
  - `metadata` object: This is any additional metadata associated with the trace.
  - `tags` string[]: This is any tags associated with the trace, which helps with grouping traces and filtering them on the Confident AI platform.
  - `spans` union[]: This is the list of base spans associated with the trace.
    - union
      - BaseSpan
        - `uuid` string, required: This is the unique identifier of the span.
        - `name` string, required: This is the name of the span.
        - `input` string: This is the input to the span.
        - `output` string: This is the output of the span.
        - `error` string: This is the error message, if an error occurred inside the span.
        - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span.
        - `startTime` string, date-time, required: This is the time the span started.
        - `endTime` string, date-time, required: This is the time the span ended.
        - `parentUuid` string, uuid: This is the unique identifier of the span's parent span.
        - `metadata` object: This is any additional metadata associated with the span.
        - `metricCollection` string: This is the metric collection to be used for evaluating the span.
        - `type` string: This is a string that represents the type of span.
        - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation.
        - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation.
        - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
        - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `integration` string: This is the integration associated with the span.
      - LlmSpan
        - `uuid` string: This is the unique identifier of the span.
        - `name` string: This is the name of the span.
        - `input` string: This is the input to the span.
        - `output` string: This is the output of the span.
        - `error` string: This is the error message, if an error occurred inside the span.
        - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span.
        - `startTime` string, date-time: This is the time the span started.
        - `endTime` string, date-time: This is the time the span ended.
        - `parentUuid` string, uuid: This is the unique identifier of the span's parent span.
        - `metadata` object: This is any additional metadata associated with the span.
        - `metricCollection` string: This is the metric collection to be used for evaluating the span.
        - `type` string: This is a string that represents the type of span.
        - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation.
        - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation.
        - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
        - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `model` string, required: This is the LLM model used in the span.
        - `provider` string: This is the provider of the generation model used in the span.
        - `integration` string: This is the integration associated with the span.
        - `promptAlias` string: This is the alias of your prompt which is stored on Confident AI.
        - `promptCommitHash` string: This is the hash of the current prompt being logged in the llm span.
        - `promptLabel` string: This is the label assigned to a specific version of prompt on the Confident AI platform.
        - `promptVersion` string: This is the version assigned to your prompt on Confident AI.
        - `costPerInputToken` number, float: This is the cost per input token of the LLM model.
        - `costPerOutputToken` number, float: This is the cost per output token of the LLM model.
        - `inputTokenCount` integer: This is the number of input tokens passed to the LLM model.
        - `outputTokenCount` integer: This is the number of output tokens generated by the LLM model.
      - RetrieverSpan
        - `uuid` string: This is the unique identifier of the span.
        - `name` string: This is the name of the span.
        - `input` string: This is the input to the span.
        - `output` string: This is the output of the span.
        - `error` string: This is the error message, if an error occurred inside the span.
        - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span.
        - `startTime` string, date-time: This is the time the span started.
        - `endTime` string, date-time: This is the time the span ended.
        - `parentUuid` string, uuid: This is the unique identifier of the span's parent span.
        - `metadata` object: This is any additional metadata associated with the span.
        - `metricCollection` string: This is the metric collection to be used for evaluating the span.
        - `type` string: This is a string that represents the type of span.
        - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation.
        - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation.
        - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
        - `integration` string: This is the integration associated with the span.
        - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `embedder` string, required: This is the embedder model used in the span.
        - `topK` integer: This is the top K chunks retrieved from your knowledge base.
        - `chunkSize` integer: This is the chunk size of each retrieved context.
      - ToolSpan
        - `uuid` string: This is the unique identifier of the span.
        - `name` string: This is the name of the span.
        - `input` string: This is the input to the span.
        - `output` string: This is the output of the span.
        - `error` string: This is the error message, if an error occurred inside the span.
        - `integration` string: This is the integration associated with the span.
        - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span.
        - `startTime` string, date-time: This is the time the span started.
        - `endTime` string, date-time: This is the time the span ended.
        - `parentUuid` string, uuid: This is the unique identifier of the span's parent span.
        - `metadata` object: This is any additional metadata associated with the span.
        - `metricCollection` string: This is the metric collection to be used for evaluating the span.
        - `type` string: This is a string that represents the type of span.
        - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation.
        - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation.
        - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
        - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `description` string: This is the description of the tool used in the span.
      - AgentSpan
        - `uuid` string: This is the unique identifier of the span.
        - `name` string: This is the name of the span.
        - `input` string: This is the input to the span.
        - `output` string: This is the output of the span.
        - `integration` string: This is the integration associated with the span.
        - `error` string: This is the error message, if an error occurred inside the span.
        - `status` 'SUCCESS' | 'ERRORED': This represents the error status of the span.
        - `startTime` string, date-time: This is the time the span started.
        - `endTime` string, date-time: This is the time the span ended.
        - `parentUuid` string, uuid: This is the unique identifier of the span's parent span.
        - `metadata` object: This is any additional metadata associated with the span.
        - `metricCollection` string: This is the metric collection to be used for evaluating the span.
        - `type` string: This is a string that represents the type of span.
        - `retrievalContext` string[]: This is the retrieval context of your span, which is to be used for evaluation.
        - `context` string[]: This is the ideal retrieval context of your span, which is to be used for evaluation.
        - `expectedOutput` string: This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
        - `toolsCalled` ToolCallData[]: This is the tools called by your span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `expectedTools` ToolCallData[]: This is the expected tools to be called by the span, which is to be used for evaluation.
          - `name` string, required: This is the name of the tool.
          - `description` string, required: This is the description of the tool.
          - `inputParameters` object: This is the input parameters that are passed to the tool.
          - `output` string: This is the output of the tool.
          - `reasoning` string: This is the reasoning your LLM provided for the tool call.
        - `availableTools` string[]: This is the list of names of available tools to be used in the span.
        - `agentHandoffs` string[]: This is the list of potential agent handoffs in the span.
  - `threadId` string: This is the unique identifier of the thread associated with the trace.
  - `thread` object: Thread-level fields applied to the thread record. `thread.id` is an alternate way to specify the thread (must match top-level `threadId` if both are provided). `metadata` and `tags` only take effect when a thread id is resolvable; successive ingestions merge metadata keys, while tags replace any prior value.
    - `id` string: The thread id. Equivalent to top-level `threadId`; if both are set they must match.
    - `metadata` object, nullable: Custom key/value metadata to attach to the thread. Values can be any JSON-serializable type and are stringified server-side. Successive ingestions for the same thread merge metadata keys.
    - `tags` string[], nullable: Tags to set on the thread. Replaces any previously stored tags.
  - `userId` string: This is the unique identifier for your end user for the trace.
  - `metricCollection` string: This is the metric collection you wish to use to evaluate the trace.
  - `testRunId` string: This is the unique identifier of the test run to associate the trace with. When set, the trace becomes one test case in that test run, and `metricCollection` is required. Create a test run with the `POST /v1/test-runs` endpoint to get this id.
  - `retrievalContext` string[]: This is the retrieval context of your trace, which is to be used for evaluation.
  - `context` string[]: This is the ideal retrieval context of your trace, which is to be used for evaluation.
  - `expectedOutput` string: This is the expected output of your trace, which is the ideal actual output and to be used for evaluation.
  - `toolsCalled` ToolCallData[]: This is the tools called by your trace, which is to be used for evaluation.
    - `name` string, required: This is the name of the tool.
    - `description` string, required: This is the description of the tool.
    - `inputParameters` object: This is the input parameters that are passed to the tool.
    - `output` string: This is the output of the tool.
    - `reasoning` string: This is the reasoning your LLM provided for the tool call.
  - `expectedTools` ToolCallData[]: This is the expected tools to be called by the trace, which is to be used for evaluation.
    - `name` string, required: This is the name of the tool.
    - `description` string, required: This is the description of the tool.
    - `inputParameters` object: This is the input parameters that are passed to the tool.
    - `output` string: This is the output of the tool.
    - `reasoning` string: This is the reasoning your LLM provided for the tool call.
  - `attachments` object: Map of attachment ids to payloads for all `[DEEPEVAL:IMAGE:…]` and `[DEEPEVAL:PDF:…]` markers in this trace. Define attachments at the trace level with same ids for same instances.

## Response `200`

- CreateTraceResponse
  - `success` boolean, required: A boolean indicating the success or failure of the API call
  - `data` object, required: This maps to the trace id.
    - `id` string: This is the uuid of the trace.
  - `link` string, required: This is the URL to the trace on the Confident AI platform.
  - `deprecated` boolean, required: This is true if this endpoint is deprecated.

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-06-30** `448829180950`: 1 info
  - added the new optional request property `testRunId`
- **2026-06-29** `77c4156f18d2`: 1 warning
  - removed the request property `testRunId`
- **2026-06-29** `c77c54067665`: 1 info
  - added the new optional request property `testRunId`
- **2026-06-28** `0d196a3b614e`: 1 warning
  - removed the request property `testRunId`
- **2026-06-28** `c1fef814439e`: 1 info
  - added the new optional request property `testRunId`

[Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/traces/post.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)