When your chatbot conversation or agent run is in flight, every action becomes an event.
Bundled together they form a trace – a structured replay of what happened, step‑by‑step.

EventWhen to use
traceThe root container for a whole conversation / agent run.
llmStart and end of every LLM call.
toolCalls to a function / external tool invoked by the model.
retrieverRAG queries and the chunks they return.
logAnything else worth seeing while debugging (system prompts, branches, errors…).

The full schema lives in API ▸ Ingestion.

  1. Collect events in memory as they happen.
  2. Flush once at the end (or on fatal error).
  3. Add a log event describing the error if things blow up.
  4. Keep tracing async – never block your user.
  5. Evaluation‑only mode? Only ingest when the run came from an Avido test → check for testId from the Webhook.
  6. LLM events should contain the raw prompt & completion – strip provider JSON wrappers.

​
Ingesting events

You can send events:

  • Directly via HTTP
  • Via our SDKs (avido)
curl --request POST \
  --url https://api.avidoai.com/v0/ingest \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "events": [
    {
      "type": "trace",
      "timestamp": "2025-05-15T12:34:56.123455Z",
      "referenceId": "123e4567-e89b-12d3-a456-426614174000",
      "metadata": {
        "source": "chatbot"
      }
    },
    {
      "type": "llm",
      "event": "start",
      "traceId": "123e4567-e89b-12d3-a456-426614174000",
      "timestamp": "2025-05-15T12:34:56.123456Z",
      "modelId": "gpt-4o-2024-08-06",
      "params": {
        "temperature": 1.2
      },
      "input": [
        {
          "role": "user",
          "content": "Tell me a joke."
        }
      ]
    }
  ]
}'

​
Tip: map your IDs

If you already track a conversation / run in your own DB, pass that same ID as referenceId.
It makes liftover between your system and Avido effortless.

​
Next steps

  • Inspect traces in Traces inside the dashboard.

Need more examples or have a tricky edge case? Contact us and we’ll expand the docs! 🎯