Interaction API
curl --request POST \
--url https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"interaction": {
"conversation_id": "<string>",
"input": "<string>",
"output": "<string>",
"time_start": "<string>",
"time_end": "<string>",
"end_user": "<string>",
"team": "<string>",
"market": "<string>",
"tenure": "<string>",
"hide_content": true,
"tags": {
"country": "<string>",
"department": "<string>",
"age": "<string>"
}
},
"user_feedback": [
{
"slug": "<string>"
}
],
"traces": [
{
"model": "<string>",
"messages": [
{}
],
"output": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"cost": 123,
"source": "<string>",
"input": "<string>",
"outputs": [
"<string>"
]
}
],
"anonymize": true
}
'import requests
url = "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction"
payload = {
"interaction": {
"conversation_id": "<string>",
"input": "<string>",
"output": "<string>",
"time_start": "<string>",
"time_end": "<string>",
"end_user": "<string>",
"team": "<string>",
"market": "<string>",
"tenure": "<string>",
"hide_content": True,
"tags": {
"country": "<string>",
"department": "<string>",
"age": "<string>"
}
},
"user_feedback": [{ "slug": "<string>" }],
"traces": [
{
"model": "<string>",
"messages": [{}],
"output": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"cost": 123,
"source": "<string>",
"input": "<string>",
"outputs": ["<string>"]
}
],
"anonymize": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
interaction: {
conversation_id: '<string>',
input: '<string>',
output: '<string>',
time_start: '<string>',
time_end: '<string>',
end_user: '<string>',
team: '<string>',
market: '<string>',
tenure: '<string>',
hide_content: true,
tags: {country: '<string>', department: '<string>', age: '<string>'}
},
user_feedback: [{slug: '<string>'}],
traces: [
{
model: '<string>',
messages: [{}],
output: '<string>',
input_tokens: 123,
output_tokens: 123,
cost: 123,
source: '<string>',
input: '<string>',
outputs: ['<string>']
}
],
anonymize: true
})
};
fetch('https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'interaction' => [
'conversation_id' => '<string>',
'input' => '<string>',
'output' => '<string>',
'time_start' => '<string>',
'time_end' => '<string>',
'end_user' => '<string>',
'team' => '<string>',
'market' => '<string>',
'tenure' => '<string>',
'hide_content' => true,
'tags' => [
'country' => '<string>',
'department' => '<string>',
'age' => '<string>'
]
],
'user_feedback' => [
[
'slug' => '<string>'
]
],
'traces' => [
[
'model' => '<string>',
'messages' => [
[
]
],
'output' => '<string>',
'input_tokens' => 123,
'output_tokens' => 123,
'cost' => 123,
'source' => '<string>',
'input' => '<string>',
'outputs' => [
'<string>'
]
]
],
'anonymize' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction"
payload := strings.NewReader("{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}"
response = http.request(request)
puts response.read_bodyInstrument (Core)
Interaction API
POST
/
event-ingestion
/
api
/
v3
/
events
/
trace_interaction
Interaction API
curl --request POST \
--url https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"interaction": {
"conversation_id": "<string>",
"input": "<string>",
"output": "<string>",
"time_start": "<string>",
"time_end": "<string>",
"end_user": "<string>",
"team": "<string>",
"market": "<string>",
"tenure": "<string>",
"hide_content": true,
"tags": {
"country": "<string>",
"department": "<string>",
"age": "<string>"
}
},
"user_feedback": [
{
"slug": "<string>"
}
],
"traces": [
{
"model": "<string>",
"messages": [
{}
],
"output": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"cost": 123,
"source": "<string>",
"input": "<string>",
"outputs": [
"<string>"
]
}
],
"anonymize": true
}
'import requests
url = "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction"
payload = {
"interaction": {
"conversation_id": "<string>",
"input": "<string>",
"output": "<string>",
"time_start": "<string>",
"time_end": "<string>",
"end_user": "<string>",
"team": "<string>",
"market": "<string>",
"tenure": "<string>",
"hide_content": True,
"tags": {
"country": "<string>",
"department": "<string>",
"age": "<string>"
}
},
"user_feedback": [{ "slug": "<string>" }],
"traces": [
{
"model": "<string>",
"messages": [{}],
"output": "<string>",
"input_tokens": 123,
"output_tokens": 123,
"cost": 123,
"source": "<string>",
"input": "<string>",
"outputs": ["<string>"]
}
],
"anonymize": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
interaction: {
conversation_id: '<string>',
input: '<string>',
output: '<string>',
time_start: '<string>',
time_end: '<string>',
end_user: '<string>',
team: '<string>',
market: '<string>',
tenure: '<string>',
hide_content: true,
tags: {country: '<string>', department: '<string>', age: '<string>'}
},
user_feedback: [{slug: '<string>'}],
traces: [
{
model: '<string>',
messages: [{}],
output: '<string>',
input_tokens: 123,
output_tokens: 123,
cost: 123,
source: '<string>',
input: '<string>',
outputs: ['<string>']
}
],
anonymize: true
})
};
fetch('https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'interaction' => [
'conversation_id' => '<string>',
'input' => '<string>',
'output' => '<string>',
'time_start' => '<string>',
'time_end' => '<string>',
'end_user' => '<string>',
'team' => '<string>',
'market' => '<string>',
'tenure' => '<string>',
'hide_content' => true,
'tags' => [
'country' => '<string>',
'department' => '<string>',
'age' => '<string>'
]
],
'user_feedback' => [
[
'slug' => '<string>'
]
],
'traces' => [
[
'model' => '<string>',
'messages' => [
[
]
],
'output' => '<string>',
'input_tokens' => 123,
'output_tokens' => 123,
'cost' => 123,
'source' => '<string>',
'input' => '<string>',
'outputs' => [
'<string>'
]
]
],
'anonymize' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction"
payload := strings.NewReader("{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://backend.nebuly.com/event-ingestion/api/v3/events/trace_interaction")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"interaction\": {\n \"conversation_id\": \"<string>\",\n \"input\": \"<string>\",\n \"output\": \"<string>\",\n \"time_start\": \"<string>\",\n \"time_end\": \"<string>\",\n \"end_user\": \"<string>\",\n \"team\": \"<string>\",\n \"market\": \"<string>\",\n \"tenure\": \"<string>\",\n \"hide_content\": true,\n \"tags\": {\n \"country\": \"<string>\",\n \"department\": \"<string>\",\n \"age\": \"<string>\"\n }\n },\n \"user_feedback\": [\n {\n \"slug\": \"<string>\"\n }\n ],\n \"traces\": [\n {\n \"model\": \"<string>\",\n \"messages\": [\n {}\n ],\n \"output\": \"<string>\",\n \"input_tokens\": 123,\n \"output_tokens\": 123,\n \"cost\": 123,\n \"source\": \"<string>\",\n \"input\": \"<string>\",\n \"outputs\": [\n \"<string>\"\n ]\n }\n ],\n \"anonymize\": true\n}"
response = http.request(request)
puts response.read_bodyThe Interaction API lets you send user interactions directly to the Nebuly platform.
For
If a required field is missing entirely, the error is the standard one for that field:
object
required
Hide properties
Hide properties
string
required
The conversation id of the interaction. This parameter can be used to enforce interactions to be grouped by a specific conversation.
string
required
The user input in the interaction.An interaction must contain at least one of
input or output. If both are present and empty, the request is rejected with a 422 error (see Validation errors).string
required
The LLM output in the interaction (the text shown to the user as assistant response).An interaction must contain at least one of
input or output. If both are present and empty, the request is rejected with a 422 error (see Validation errors).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.000Zstring
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.000Zstring
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.
string
Customer-defined team segment. Any non-empty string is accepted.Example:
Engineeringstring
Customer-defined market segment. Any non-empty string is accepted.Example:
EU-Weststring
Tenure band or ISO hire date converted to a band at ingest.Accepted band values (case-insensitive):
under_1_year1_to_3_years3_to_5_years5_to_10_years10_plus_years
YYYY-MM-DD).Example: 1_to_3_years or 2019-04-12boolean
default:"false"
Boolean flag to hide the content of the interaction (input and output) in the Nebuly platform. If set to true, only metadata and traces will be visible.
object
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.object[]
A list of feedback actions provided by the end-user during or after the interaction.
As optional extra parameters is possible to include:
Hide properties
Hide properties
string
required
The type of action. Accepted values include:
thumbs_upthumbs_downcopy_inputcopy_outputpastecommentregenerateeditrating
- text (string, optional): textual feedback associated with the action (if applicable).
- value (integer, optional): only used for the
ratingaction to capture a numerical score.
"user_feedback": [
{
"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"
}
]
object[]
required
The full trace of your LLM agent or chain.
- LLMTrace
- RetrievalTrace
- EmbeddingTrace
Show properties
Show properties
string
required
The LLM used.
array
required
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.
"messages": [
{
"role": "system",
"content": "This is a system prompt"
},
{
"role": "user",
"content": "What's the weather like in Turin?"
},
{
"role": "assistant",
"content": "The weather is currently rainy in Turin."
},
{
"role": "user",
"content": "What's the weather like in Rome?"
}
]
string
required
The LLM output message.
integer
The number of input tokens.
integer
The number of output tokens.
integer
The cost of the LLM call, expressed in micro-dollars
(1 USD = 1,000,000 micro-dollars, so a cost of $0.002 is sent
as
2000). Must be a non-negative integer. When provided, this
value overrides the cost that would otherwise be computed
automatically from the model, input_tokens and
output_tokens. Use it to report the exact cost of the call
(e.g. for models or providers whose pricing Nebuly does not
compute automatically, or to account for custom or negotiated
pricing).boolean
default:"true"
Boolean flag to anonymize your data
Validation errors
Every interaction must contain at least one ofinput or output. If both are present and empty, the interaction is rejected with HTTP status 422 Unprocessable Entity and nothing is stored. If a field is missing entirely, the standard Field required error is returned for that field instead. The same validation applies to the v1, v2 and v3 interaction and conversation ingestion endpoints.
Validation errors on these endpoints return a trimmed body: each entry in detail contains only type, loc and msg.
{
"detail": [
{
"type": "value_error",
"loc": [
"body",
"interaction"
],
"msg": "Value error, Interaction must have at least input or output"
}
]
}
trace_conversation, loc points to the offending interaction by index:
{
"detail": [
{
"type": "value_error",
"loc": ["body", "conversation", "interactions", 1],
"msg": "Value error, Interaction must have at least input or output"
}
]
}
{
"detail": [
{
"type": "missing",
"loc": ["body", "interaction", "input"],
"msg": "Field required"
}
]
}