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>",
    "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>",
        "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>',
      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>',
        '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    \"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    \"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    \"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_body

POST

event-ingestion

api

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>",
    "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>",
        "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>',
      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>',
        '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    \"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    \"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    \"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_body

The Interaction API lets you send user interactions directly to the Nebuly platform.

object

required

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.

string

required

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

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

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

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.

boolean

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.

Show Tags examples

string

default:"US"

The end user’s country.

string

default:"Finance"

The end user’s department.

string

default:"20-30"

The end user’s age group.

object[]

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

Hide properties

string

required

The type of action. Accepted values include:

thumbs_up
thumbs_down
copy_input
copy_output
paste
comment
regenerate
edit
rating

As optional extra parameters is possible to include:

text (string, optional): textual feedback associated with the action (if applicable).
value (integer, optional): only used for the rating action to capture a numerical score.

Example:

"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

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.

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": "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).

Embedding trace details for an LLM.

Show properties

string

required

The model used for embedding.

string

required

The input text to be embedded. Example:

"input": "Text to be embedded"

integer

The number of input tokens. Example:

"input_tokens": 10

boolean

default:"true"

Boolean flag to anonymize your data

Introduction

Delete Interactions

⌘I

Getting started

Instrument (Core)

Instrument (Optional)

Eligible Users

Insights API

Reports API

Utilities

Interaction API