Send conversation with interaction traces

POST

event-ingestion

api

events

trace_conversation

Send conversation with interaction traces

curl --request POST \
  --url https://backend.nebuly.com/event-ingestion/api/v2/events/trace_conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "conversation": {
    "interactions": [
      {
        "input": "<string>",
        "output": "<string>",
        "time_start": "<string>",
        "time_end": "<string>",
        "tags": {},
        "feedback_actions": [
          {}
        ],
        "trace": [
          {
            "model": "<string>",
            "messages": [
              {}
            ],
            "output": "<string>",
            "input_tokens": 123,
            "output_tokens": 123,
            "source": "<string>",
            "input": "<string>",
            "outputs": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "end_user": "<string>"
  }
}'

For users of the european region, the correct endpoint is https://backend.eu.nebuly.com/event-ingestion/api/v2/events/trace_conversation.

You can use this endpoint to send the full conversation between the user and the AI system. This approach allows to send interactions (with their traces) in a single request. This endpoint is designed for sending data asynchronously in bulk once conversations are completed.

conversation

object

required

The conversation an user is having with an LLM based assistant.

Show conversation properties

interactions

object[]

required

The interaction to send to the nebuly platform.

Show properties

input

string

required

The user input in the interaction.

output

string

required

The LLM output in the interaction (the text shown to the user as assistant response).

time_start

string

required

The start time of the call to the LLM. You can approximate this to the time when the user sends the interaction. The accepted format is the ISO 8601.

Example: 2023-12-07T15:00:00.000Z

time_end

string

required

The end time of the call to the LLM. This is when the user receives the full answer from the model. The accepted format is the ISO 8601.

Example: 2023-12-07T15:00:00.000Z

tags

dict<string, string>

Tag user interactions by adding key-value pairs using this parameter. Each key represents the tag name, and the corresponding value is the tag value.

For example, if you want to tag an interaction with the model version used to reply to user input, provide it as an argument for nebuly_tags, e.g. {"version" => "v1.0.0"}. You have the flexibility to define custom tags, making them available as potential filters on the Nebuly platform.

feedback_actions

object[]

A list of feedback actions provided by the end-user during or after the interaction.

Each object in the array can contain:

slug: (string) – the type of action. Accepted values include:
- thumbs_up
- thumbs_down
- copy_input
- copy_output
- paste
- comment
- regenerate
- edit
- rating
text: (string, optional) – textual feedback associated with the action (if applicable).
value: (number, optional) – only used for the rating action to capture a numerical score.

Example:

"feedback_actions": [
    {
    "slug": "thumbs_up",
    "text": "Very helpful response!"
    },
    {
    "slug": "comment",
    "text": "Can you explain more about this?"
    },
    {
    "slug": "rating",
    "value": 4,
    "text": "Pretty good!"
    },
    {
    "slug": "regenerate"
    }
]

trace

object[]

The full trace of your LLM agent or chain. There are two kind of steps that can compose a trace:

The intermediate call to an LLM.

Show properties

model

string

required

The LLM used.

messages

object[]

A list of messages from the conversation so far, following the same format used by OpenAI Chat Completion endpoints.

Each message has two required fields:

role: the role of who is sending the message. Possible values are: system, user, assistant, tool.
content: the content of the message.

The messages in the list should be ordered according to the conversation’s sequence, from the oldest message to the most recent. Example:

"messages": [
    {
        "role": "system",
        "content: "This is a system prompt"
    },
    {
        "role": "user",
        "content": "user input 1"
    },
    {
        "role": "assistant",
        "content": "assistant response 1"
    },
    {
        "role": "user",
        "content": "user input"
    }
]

output

string

required

The LLM output message.

input_tokens

integer

The number of input tokens.

output_tokens

integer

The number of output tokens.

The intermediate call to an LLM.

Show properties

model

string

required

The LLM used.

messages

object[]

A list of messages from the conversation so far, following the same format used by OpenAI Chat Completion endpoints.

Each message has two required fields:

role: the role of who is sending the message. Possible values are: system, user, assistant, tool.
content: the content of the message.

The messages in the list should be ordered according to the conversation’s sequence, from the oldest message to the most recent. Example:

"messages": [
    {
        "role": "system",
        "content: "This is a system prompt"
    },
    {
        "role": "user",
        "content": "user input 1"
    },
    {
        "role": "assistant",
        "content": "assistant response 1"
    },
    {
        "role": "user",
        "content": "user input"
    }
]

output

string

required

The LLM output message.

input_tokens

integer

The number of input tokens.

output_tokens

integer

The number of output tokens.

The intermediate call to a retriever tool (vector db) or agent tool (function calling).

Show properties

source

string

required

The type of data source used, e.g. db_reader_tool or vector_db.

input

string

required

The query to the RAG source.

outputs

string[]

required

The RAG source output. It is presented in list format to accommodate multiple outputs for a single query.

Embedding trace details for an LLM.

Show properties

model

string

required

The model used for embedding.

input

string

required

The input text to be embedded. Example:

"input": "Text to be embedded"

input_tokens

integer

The number of input tokens. Example:

"input_tokens": 10

end_user

string

required

An id or username uniquely identifying the end-user. We recommend hashing their username or email address, in order to avoid sending us any identifying information.

Send Interaction Send Feedback Actions

Send conversation with interaction traces

curl --request POST \
  --url https://backend.nebuly.com/event-ingestion/api/v2/events/trace_conversation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "conversation": {
    "interactions": [
      {
        "input": "<string>",
        "output": "<string>",
        "time_start": "<string>",
        "time_end": "<string>",
        "tags": {},
        "feedback_actions": [
          {}
        ],
        "trace": [
          {
            "model": "<string>",
            "messages": [
              {}
            ],
            "output": "<string>",
            "input_tokens": 123,
            "output_tokens": 123,
            "source": "<string>",
            "input": "<string>",
            "outputs": [
              "<string>"
            ]
          }
        ]
      }
    ],
    "end_user": "<string>"
  }
}'

Welcome

Tracking

Embedded Pages

AB Testing

Platform users

SDK

Send conversation with interaction traces