Trace Ingestion

POSThttps://api.confident-ai.com/v1/traces

Creates a new trace on Confident AI.

POST/v1/traces

curl -X POST "https://api.confident-ai.com/v1/traces" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "uuid": "string",
  "name": "string",
  "input": "string",
  "output": "string",
  "startTime": "2026-01-01T00:00:00Z",
  "endTime": "2026-01-01T00:00:00Z",
  "environment": "production",
  "metadata": {},
  "tags": [
    "string"
  ],
  "spans": [
    {
      "uuid": "string",
      "name": "string",
      "input": "string",
      "output": "string",
      "error": "string",
      "status": "SUCCESS",
      "startTime": "2026-01-01T00:00:00Z",
      "endTime": "2026-01-01T00:00:00Z",
      "parentUuid": "string",
      "metadata": {},
      "metricCollection": "string",
      "type": "string",
      "retrievalContext": [
        "string"
      ],
      "context": [
        "string"
      ],
      "expectedOutput": "string",
      "toolsCalled": [
        {
          "name": "string",
          "description": "string",
          "inputParameters": {},
          "output": "string",
          "reasoning": "string"
        }
      ],
      "expectedTools": [
        {
          "name": "string",
          "description": "string",
          "inputParameters": {},
          "output": "string",
          "reasoning": "string"
        }
      ],
      "integration": "string"
    }
  ],
  "threadId": "string",
  "thread": {
    "id": "string",
    "metadata": {},
    "tags": [
      "string"
    ]
  },
  "userId": "string",
  "metricCollection": "string",
  "testRunId": "string",
  "retrievalContext": [
    "string"
  ],
  "context": [
    "string"
  ],
  "expectedOutput": "string",
  "toolsCalled": [
    {
      "name": "string",
      "description": "string",
      "inputParameters": {},
      "output": "string",
      "reasoning": "string"
    }
  ],
  "expectedTools": [
    {
      "name": "string",
      "description": "string",
      "inputParameters": {},
      "output": "string",
      "reasoning": "string"
    }
  ],
  "attachments": {}
}'

200

{
  "success": true,
  "data": {
    "id": "string"
  },
  "link": "string",
  "deprecated": true
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Request body

uuidstringRequired
This is the unique identifier of the trace.
namestring
This is the name of the trace.
inputstring
This is the input to the trace.
outputstring
This is the output of the trace.
startTimestringRequired
This is the time the trace started.
endTimestringRequired
This is the time the trace ended.
environmentenum
This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform.
Show 4 enum valuesHide 4 enum values
- production
- development
- staging
- testing
metadataobject
This is any additional metadata associated with the trace.
tagslist of strings
This is any tags associated with the trace, which helps with grouping traces and filtering them on the Confident AI platform.
spanslist of object | object | object | object | object
This is the list of base spans associated with the trace.
Show 5 variantsHide 5 variants
- BaseSpanobject
  Show 18 propertiesHide 18 properties
  - uuidstringRequired
    This is the unique identifier of the span.
  - namestringRequired
    This is the name of the span.
  - inputstring
    This is the input to the span.
  - outputstring
    This is the output of the span.
  - errorstring
    This is the error message, if an error occurred inside the span.
  - statusenum
    This represents the error status of the span.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestringRequired
    This is the time the span started.
  - endTimestringRequired
    This is the time the span ended.
  - parentUuidstring
    This is the unique identifier of the span's parent span.
  - metadataobject
    This is any additional metadata associated with the span.
  - metricCollectionstring
    This is the metric collection to be used for evaluating the span.
  - typestring
    This is a string that represents the type of span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - integrationstring
    This is the integration associated with the span.
- OR
- LlmSpanobject
  Show 28 propertiesHide 28 properties
  - uuidstring
    This is the unique identifier of the span.
  - namestring
    This is the name of the span.
  - inputstring
    This is the input to the span.
  - outputstring
    This is the output of the span.
  - errorstring
    This is the error message, if an error occurred inside the span.
  - statusenum
    This represents the error status of the span.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - parentUuidstring
    This is the unique identifier of the span's parent span.
  - metadataobject
    This is any additional metadata associated with the span.
  - metricCollectionstring
    This is the metric collection to be used for evaluating the span.
  - typestring
    This is a string that represents the type of span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - modelstringRequired
    This is the LLM model used in the span.
  - providerstring
    This is the provider of the generation model used in the span.
  - integrationstring
    This is the integration associated with the span.
  - promptAliasstring
    This is the alias of your prompt which is stored on Confident AI.
  - promptCommitHashstring
    This is the hash of the current prompt being logged in the llm span.
  - promptLabelstring
    This is the label assigned to a specific version of prompt on the Confident AI platform.
  - promptVersionstring
    This is the version assigned to your prompt on Confident AI.
  - costPerInputTokennumber
    This is the cost per input token of the LLM model.
  - costPerOutputTokennumber
    This is the cost per output token of the LLM model.
  - inputTokenCountinteger
    This is the number of input tokens passed to the LLM model.
  - outputTokenCountinteger
    This is the number of output tokens generated by the LLM model.
- OR
- RetrieverSpanobject
  Show 21 propertiesHide 21 properties
  - uuidstring
    This is the unique identifier of the span.
  - namestring
    This is the name of the span.
  - inputstring
    This is the input to the span.
  - outputstring
    This is the output of the span.
  - errorstring
    This is the error message, if an error occurred inside the span.
  - statusenum
    This represents the error status of the span.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - parentUuidstring
    This is the unique identifier of the span's parent span.
  - metadataobject
    This is any additional metadata associated with the span.
  - metricCollectionstring
    This is the metric collection to be used for evaluating the span.
  - typestring
    This is a string that represents the type of span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - integrationstring
    This is the integration associated with the span.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - embedderstringRequired
    This is the embedder model used in the span.
  - topKinteger
    This is the top K chunks retrieved from your knowledge base.
  - chunkSizeinteger
    This is the chunk size of each retrieved context.
- OR
- ToolSpanobject
  Show 19 propertiesHide 19 properties
  - uuidstring
    This is the unique identifier of the span.
  - namestring
    This is the name of the span.
  - inputstring
    This is the input to the span.
  - outputstring
    This is the output of the span.
  - errorstring
    This is the error message, if an error occurred inside the span.
  - integrationstring
    This is the integration associated with the span.
  - statusenum
    This represents the error status of the span.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - parentUuidstring
    This is the unique identifier of the span's parent span.
  - metadataobject
    This is any additional metadata associated with the span.
  - metricCollectionstring
    This is the metric collection to be used for evaluating the span.
  - typestring
    This is a string that represents the type of span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - descriptionstring
    This is the description of the tool used in the span.
- OR
- AgentSpanobject
  Show 20 propertiesHide 20 properties
  - uuidstring
    This is the unique identifier of the span.
  - namestring
    This is the name of the span.
  - inputstring
    This is the input to the span.
  - outputstring
    This is the output of the span.
  - integrationstring
    This is the integration associated with the span.
  - errorstring
    This is the error message, if an error occurred inside the span.
  - statusenum
    This represents the error status of the span.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the span started.
  - endTimestring
    This is the time the span ended.
  - parentUuidstring
    This is the unique identifier of the span's parent span.
  - metadataobject
    This is any additional metadata associated with the span.
  - metricCollectionstring
    This is the metric collection to be used for evaluating the span.
  - typestring
    This is a string that represents the type of span.
  - retrievalContextlist of strings
    This is the retrieval context of your span, which is to be used for evaluation.
  - contextlist of strings
    This is the ideal retrieval context of your span, which is to be used for evaluation.
  - expectedOutputstring
    This is the expected output of your span, which is the ideal actual output and to be used for evaluation.
  - toolsCalledlist of objects
    This is the tools called by your span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - expectedToolslist of objects
    This is the expected tools to be called by the span, which is to be used for evaluation.
    Show 5 propertiesHide 5 properties
    namestringRequired
    This is the name of the tool.
    descriptionstringRequired
    This is the description of the tool.
    inputParametersobject
    This is the input parameters that are passed to the tool.
    outputstring
    This is the output of the tool.
    reasoningstring
    This is the reasoning your LLM provided for the tool call.
  - availableToolslist of strings
    This is the list of names of available tools to be used in the span.
  - agentHandoffslist of strings
    This is the list of potential agent handoffs in the span.
threadIdstring
This is the unique identifier of the thread associated with the trace.
threadobject
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.
Show 3 propertiesHide 3 properties
- idstring
  The thread id. Equivalent to top-level threadId; if both are set they must match.
- metadataobject
  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.
- tagslist of strings
  Tags to set on the thread. Replaces any previously stored tags.
userIdstring
This is the unique identifier for your end user for the trace.
metricCollectionstring
This is the metric collection you wish to use to evaluate the trace.
testRunIdstring
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.
retrievalContextlist of strings
This is the retrieval context of your trace, which is to be used for evaluation.
contextlist of strings
This is the ideal retrieval context of your trace, which is to be used for evaluation.
expectedOutputstring
This is the expected output of your trace, which is the ideal actual output and to be used for evaluation.
toolsCalledlist of objects
This is the tools called by your trace, which is to be used for evaluation.
Show 5 propertiesHide 5 properties
- namestringRequired
  This is the name of the tool.
- descriptionstringRequired
  This is the description of the tool.
- inputParametersobject
  This is the input parameters that are passed to the tool.
- outputstring
  This is the output of the tool.
- reasoningstring
  This is the reasoning your LLM provided for the tool call.
expectedToolslist of objects
This is the expected tools to be called by the trace, which is to be used for evaluation.
Show 5 propertiesHide 5 properties
- namestringRequired
  This is the name of the tool.
- descriptionstringRequired
  This is the description of the tool.
- inputParametersobject
  This is the input parameters that are passed to the tool.
- outputstring
  This is the output of the tool.
- reasoningstring
  This is the reasoning your LLM provided for the tool call.
attachmentsobject
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

successboolean
A boolean indicating the success or failure of the API call
dataobject
This maps to the trace id.
Show 1 propertyHide 1 property
- idstring
  This is the uuid of the trace.
linkstring
This is the URL to the trace on the Confident AI platform.
deprecatedboolean
This is true if this endpoint is deprecated.

Built byConfident AI