Get a single trace by ID

GET

traces

{id}

curl --request GET \
  --url https://api.avidoai.com/v0/traces/{id} \
  --header 'x-api-key: <api-key>' \
  --header 'x-application-id: <api-key>'

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "traceId": "thread_abc",
    "applicationId": "app_123",
    "timestamp": "2025-01-05T12:34:56.789Z",
    "type": "llm",
    "event": "start",
    "tokens": {
      "input": 100,
      "output": 200
    },
    "metadata": {
      "custom": "metadata"
    }
  }
}

Authorizations

x-api-key

string

header

required

Your unique Avido API key

x-application-id

string

header

required

Your unique application ID. Get this from the Connections page in Avido.

Path Parameters

string

required

The unique identifier of the trace

Example:

"123e4567-e89b-12d3-a456-426614174000"

Response

200

application/json

Successfully retrieved trace

Successful response containing a single trace object

data

object

required

A trace grouping related steps (e.g. a user-agent interaction or conversation).

data.id

string

required

Unique Trace ID (UUID).

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.timestamp

string

required

ISO-8601 datetime when the trace was created.

Example:

"2025-01-05T12:34:56.789Z"

data.referenceId

string

An optional reference ID to link the trace to an existing conversation or interaction in your own database.

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.metadata

object | null

Arbitrary metadata (e.g., userId, source). String inputs are parsed as JSON or wrapped in { raw: val }.

Example:

{ "userId": "123", "source": "chatbot" }

data.testId

string | null

The associated Test if this was triggered by an Avido eval

data.steps

object[] | null

The steps associated with the trace.

Schema for LLM trace events.

data.steps.id

string

required

UUID for the step.

Example:

"123e4567-e89b-12d3-a456-426614174000"

data.steps.traceId

string

required

UUID referencing the parent trace's ID.

Example:

"610adba1-7cc0-4fa7-9e2b-8bd2fdf281b2"

data.steps.timestamp

string

required

ISO-8601 datetime for when the step occurred.

Example:

"2025-01-05T12:34:56.789Z"

data.steps.type

enum<string>

required

Available options:

llm

data.steps.modelId

string

required

Model ID or name used for the LLM call.

Example:

"gpt-4o-2024-08-06"

data.steps.params

Arbitrary params for the step.

data.steps.metadata

object | null

Extra metadata about this trace event. String values are parsed as JSON if possible.

data.steps.usage

object | null

Number of input and output tokens used by the LLM.

Example:

{
  "promptTokens": 100,
  "completionTokens": 100
}

data.steps.input

JSON input for this LLM trace event (e.g., the prompt).

Example:

{
  "role": "user",
  "content": "Tell me a joke."
}

data.steps.output

JSON describing the output. String inputs are parsed or wrapped in { message: val }.

Example:

{
  "message": "Why did the chicken cross the road?"
}

data.steps.event

string | null

Event label (e.g., 'start', 'end'). Specific to LLM traces.

Example:

"end"

List Traces Ingest events

curl --request GET \
  --url https://api.avidoai.com/v0/traces/{id} \
  --header 'x-api-key: <api-key>' \
  --header 'x-application-id: <api-key>'

{
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "traceId": "thread_abc",
    "applicationId": "app_123",
    "timestamp": "2025-01-05T12:34:56.789Z",
    "type": "llm",
    "event": "start",
    "tokens": {
      "input": 100,
      "output": 200
    },
    "metadata": {
      "custom": "metadata"
    }
  }
}

Webhook

Applications

Threads

Ingestion

Tasks

Evals

Tests

Topics

Runs

Style Guides

Get a single trace by ID

Authorizations

Path Parameters

Response