Search Chatbot traces - Fluid Topics - Latest

Fluid Topics API Reference Guide

Category
Reference Guides
Audience
public
Version
Latest

This web service allows users with the ADMIN or BEHAVIOR_DATA_USER role to list interactions with chatbot profiles.

The Search Chatbot traces web service does not include conversations with the Agentic chatbot component.

Method Endpoint
POST
/api/admin/ai/rag/chat/conversations

Request body

The following example shows a JSON request body for this web service:

{
  "nbResults": 25,
  "startDate": "2025-10-27",
  "endDate": "2025-10-31",
  "types": ["AGENT"]
}

The JSON request body expects the following fields:

Field Type Required? Description
nbResults Number No Number of expected results. The maximum value is 1000, and the default value is 50.
If there are more than 1000 conversations, the 1000 conversations returned by the web service are the 1000 most recent conversations.
startDate String No The inclusive start date of the period. The expected format is YYYY-MM-DD.
endDate String No The exclusive end date of the period. The expected format is YYYY-MM-DD.
For traces of the current day, enter the next day's date.
types List No The type of trace to return. The accepted values are RAG and AGENT. An empty list returns both types.

Response body

{
  "startDate": "2025-01-01",
  "endDate": "2026-01-01",
  "nbResults": 2,
  "results": [
    {
      "type": "RAG",
      "id": "rag-id",
      "timestamp": "2025-06-01",
      "sessionId": "sessionId",
      "userId": "userId",
      "conversationId": "rag-conversation-id",
      "profileId": "profileId",
      "input": {
        "query": "query ?",
        "userInstructions": "userInstructions",
        "history": [{ "role": "USER", "content": "previous question" }]
      },
      "output": { "response": "response !" },
      "ratings": []
    },
    {
      "type": "AGENT",
      "id": "agent-id",
      "timestamp": "2025-06-02",
      "sessionId": "sessionId",
      "userId": "userId",
      "conversationId": "agent-conversation-id",
      "profileId": "profileId",
      "input": {
        "query": "search book",
        "history": [
          { "role": "USER", "content": "hi" },
          { "role": "ASSISTANT", "content": { "message": "Hello", "sources": [] } }
        ],
      },
      "output": {
        "message": "Done",
        "sources": [
          {
            "publicationType": "TOPIC",
            "title": "title",
            "publicationId": "publication-id",
            "contentId": "content-id",
            "excerpt": "excerpt",
            "contentUrl": "url"
          }
        ]
      },
      "ratings": [
        {
          "value": 0,
          "timestamp": "2025-06-03",
          "userId": "userId",
          "source": "TRACES_REVIEW",
          "tags": ["INACCURATE"],
          "comment": "This is a comment."
        }
      ]
    }
  ]
}
Field Type Description
nbResults Number The number of conversations found.
results Array A list of conversations between users and Chatbots.
type List The type of trace. Possible values are RAG and AGENT.
id String The trace's unique ID.
timestamp String The UTC date and time for the first message, in ISO-8601 format (YYYY-MM-DDTHH:MM:SS with microseconds).
sessionId String The session ID. A user can have multiple conversations with Chatbots in the same session.
userId String The user's ID.
conversationId String The conversation's unique ID.
profileId String An AI profile ID.
input Object Contains information which inform the Chatbot's answer to the query.
query String The last message sent by the user to the Chatbot in the conversation.
userInstructions String The AI profile Chatbot instructions.
history Array An array of message sent by the user and the Chatbot to one another, in chronological order. The first element of the array is the oldest message.
Conversations can be ongoing, which means that additional messages can appear in later calls to this web service.
role String Can be ai for the Chatbot, or human for the user talking to the Chatbot.
content String The content of the user or Chatbot message.
output Object Contains the Chatbot answer to the last user message.
response String The answer to the last message sent by the Chatbot to the user in the conversation.
ratings Array An array containing the possible user and administrator ratings.
value Number The rating value. 0 is negative, and 1 is positive.
timestamp String The UTC date and time for the query to the LLM, in ISO-8601 format (YYYY-MM-DDTHH:MM:SS with microseconds).
source String Can be TRACES_REVIEW for an ADMIN rating from the Chatbot traces menu, or CHATBOT for a user rating from the Chatbot component.
userId String The user's ID.
tags Array A list of issues associated with negative feedback. It is only possible to add a tag if the value field is 0.

Possible values are:
  • INACCURATE
  • INCOMPLETE
  • OFF_TOPIC
  • IRRELEVANT_SOURCES
  • SLOW
  • OTHER
comment String A comment associated with the rating.
Comments are limited to 5000 characters.