List Traces

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

Lists the traces in your Confident AI project one page at a time, newest first by default. Filter by environment, time window and metadata, and pass nextCursor back as cursor for the next page. Each trace is returned as a summary with a preview of its input and output; retrieve a trace by uuid for its spans, evaluation fields, results and annotations.

GET/v2/traces

curl -X GET "https://api.confident-ai.com/v2/traces" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>"

200

{
  "success": true,
  "data": {
    "traces": [
      {
        "uuid": "<TRACE-UUID>",
        "name": "Geography QA",
        "status": "SUCCESS",
        "startTime": "2025-01-15T10:30:00.000Z",
        "endTime": "2025-01-15T10:30:05.000Z",
        "latency": 5000,
        "cost": 0.00018,
        "threadId": "thread-42",
        "userId": "end-user-42",
        "environment": "production",
        "tags": [
          "geography"
        ],
        "metadata": {
          "client": "acme-corp"
        },
        "inputPreview": "What is the capital of France?",
        "outputPreview": "The capital of France is Paris."
      }
    ],
    "totalTraces": 1,
    "nextCursor": null
  },
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The API key of your Confident AI project.

Query parameters

pageSizeintegerdefault: 25
The number of results per page, at most 100. Defaults to 25.
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.
startstring
This filters for results created at or after the specified start datetime, in ISO 8601 format. Defaults to 60 days ago.
endstring
This filters for results created before the specified end datetime, in ISO 8601 format. Defaults to the current time.
ascendingenumdefault: false
This determines if the field specified in sortBy should be in ascending order. Defaults to false, which returns the newest results first.
sortByenumdefault: createdAt
This determines the field to sort by. Defaults to createdAt.
environmentenum
This filters the traces by the environment where the trace was created, and returns traces from all environments if not specified.
metadataobject
Filter traces by metadata key-value pairs using bracket notation, for example metadata[client]=acme-corp. Every pair must match.

Response

List Traces succeeded.

successboolean
Indicates if the request was successful.
dataobject
Show 3 propertiesHide 3 properties
- traceslist of objects
  This is the list of traces for the current page.
  Show 14 propertiesHide 14 properties
  - uuidstring
    This is the unique identifier of the trace.
  - namestring | null
    This is the name of the trace.
  - statusenum
    This represents the error status of a trace or span: SUCCESS when it completed, ERRORED when it failed.
    Show 2 enum valuesHide 2 enum values
    SUCCESS
    ERRORED
  - startTimestring
    This is the time the trace started.
  - endTimestring
    This is the time the trace ended.
  - latencyinteger
    This is how long the trace took, in milliseconds.
  - costnumber | null
    This is the total cost of the trace in USD, summed from its spans, or null when it is not known.
  - threadIdstring | null
    This is the thread id of the trace, which groups traces in the same thread into a conversation, or null when the trace is not part of one.
  - userIdstring | null
    This is the user id you provided for this trace, or null when you did not.
  - 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
  - tagsarray | null
    This is the list of tags associated with the trace, which is useful for grouping and filtering for traces.
  - metadataobject | null
    This is any additional metadata associated with the trace.
  - inputPreviewstring | null
    The first characters of the trace's input, or null when it has none. Retrieve the trace by id for the full value.
  - outputPreviewstring | null
    The first characters of the trace's output, or null when it has none. Retrieve the trace by id for the full value.
- totalTracesinteger
  This is the total number of traces matching the query across all pages. Present on the first page only; omitted when a cursor is given.
- nextCursorstring | null
  The value to pass as cursor to get the next page, or null when this is the last page.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI