Trace Ingestion | Confident AI Docs

curl -X POST https://api.confident-ai.com/v1/traces \
     -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
     -H "Content-Type: application/json" \
     -d '{
  "uuid": "<TRACE-UUID>",
  "startTime": "2025-01-15T10:30:00Z",
  "endTime": "2025-01-15T10:30:05Z",
  "input": "What is the capital of France?",
  "output": "The capital of France is Paris.",
  "baseSpans": [
    {
      "uuid": "<SPAN-UUID>",
      "name": "Agent",
      "input": "What is the capital of France?",
      "output": "Let me look that up for you.",
      "startTime": "2025-01-15T10:30:00Z",
      "endTime": "2025-01-15T10:30:02Z"
    }
  ]
}'

Creates a new trace on Confident AI.

Request

uuidstringRequired

This is the unique identifier of the trace.

startTimestringRequiredformat: "date-time"

This is the time the trace started.

endTimestringRequiredformat: "date-time"

This is the time the trace ended.

namestringOptional

This is the name of the trace.

inputstringOptional

This is the input to the trace.

outputstringOptional

This is the output of the trace.

environmentenumOptional

This is the environment where your trace was posted, which helps with separating and debugging traces from different environments on the Confident AI platform.

metadatamap from strings to anyOptional

This is any additional metadata associated with the trace.

tagslist of stringsOptional

This is any tags associated with the trace, which helps with grouping traces and filtering them on the Confident AI platform.

spanslist of objectsOptional

This is the list of base spans associated with the trace.

threadIdstringOptional

This is the unique identifier of the thread associated with the trace.

threadobjectOptional

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.

userIdstringOptional

This is the unique identifier for your end user for the trace.

metricCollectionstringOptional

This is the metric collection you wish to use to evaluate the trace.

retrievalContextlist of stringsOptional

This is the retrieval context of your trace, which is to be used for evaluation.

contextlist of stringsOptional

This is the ideal retrieval context of your trace, which is to be used for evaluation.

expectedOutputstringOptional

This is the expected output of your trace, which is the ideal actual output and to be used for evaluation.

toolsCalledlist of objectsOptional

This is the tools called by your trace, which is to be used for evaluation.

expectedToolslist of objectsOptional

This is the expected tools to be called by the trace, which is to be used for evaluation.

attachmentsmap from strings to objectsOptional

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.

linkstring

This is the URL to the trace on the Confident AI platform.

deprecatedboolean

This is true if this endpoint is deprecated.

1	{
2	"success": true,
3	"data": {
4	"id": "TRACE-ID"
5	},
6	"link": "https://app.confident-ai.com/project/<PROJECT_ID>/observatory/traces/TRACE-ID",
7	"deprecated": false
8	}

Headers

Request

Response