Launch Week 02 wrapped — explore all five launches
Confident AI
Docs
Pricing
Products
LLM Evaluation
LLM Evaluation

Benchmark LLM systems with research-backed metrics.

LLM Observability
LLM Observability

Trace, monitor, and alert on production LLM systems.

AI Red Teaming
AI Red Teaming

Stress-test LLM apps against adversarial attacks.

AI Governance
AI Governance

Enforce AI standards and controls across teams.

Book a DemoSign Up
Book a DemoSign Up

List Traces

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

Retrieves a list of traces from your Confident AI project.

GET/v1/traces
curl -X GET "https://api.confident-ai.com/v1/traces" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"
200
{
  "success": true,
  "data": {
    "traces": {
      "name": "Trace Name",
      "startTime": "2025-01-15T10:30:00Z",
      "endTime": "2025-01-15T10:30:05Z",
      "uuid": "TRACE-UUID",
      "projectId": "PROJECT-ID",
      "environment": "production",
      "threadId": "THREAD-ID",
      "userId": "USER-ID",
      "tags": [
        "General QA"
      ]
    },
    "totalTraces": 1
  },
  "deprecated": false
}

Headers

  • CONFIDENT_API_KEYstringRequired

    The API key of your Confident AI project.

Query parameters

  • pageSizeinteger

    This specifies the maximum number of traces per page. Defaulted to 25.

  • environmentstring

    This filters the traces by the environment where the trace was created, and returns traces from all environments if not specified.

  • startstring

    This filters for traces created after the specified start datetime. Defaulted to 30 days ago.

  • endstring

    This filters for traces created before the specified end datetime. Defaulted to the current time.

  • sortByenum

    This determines the field to sort by. Defaulted to createdAt.

  • cursorstring

    This is used for pagination, and should be set to the nextCursor value returned in the previous response to get the next page of results

  • metadataobject

    Filter traces by metadata key-value pairs. Supports multiple keys using bracket notation.

  • ascendingenum

    This determines if the field specified in sortBy should be in ascending order. Defaults to false.

Response

  • successboolean

    This is true if the traces were successfully retrieved.

  • dataobject

    This maps to the list of traces retrieved.

    Show 2 propertiesHide 2 properties

    • traceslist of objects

      This is the list of traces retrieved.

      Show 21 propertiesHide 21 properties

      • uuidstring

        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.

      • startTimestring

        This is the time the trace started.

      • endTimestring

        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

          • 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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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.

          • modelstring

            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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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.

          • embedderstring

            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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

            • namestring

              This is the name of the tool.

            • descriptionstring

              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

        • namestring

          This is the name of the tool.

        • descriptionstring

          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

        • namestring

          This is the name of the tool.

        • descriptionstring

          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.

    • totalTracesinteger

      This is the total number of traces retrieved.

  • deprecatedboolean

    This is true if this endpoint is deprecated.

Built byConfident AI