Traces API

Traces represent conversation contexts for multi-turn interactions and execution tracking. They automatically track message history, state, and provide a unified interface for managing conversation flows.

Overview

Traces are the primary mechanism for:

Conversation context — multi-turn interactions with agents
Execution tracking — following receptor, neuron, and pathway runs
Message history — stored turns for the thread
State — context across interactions

Traces are created when the first message is added. No explicit creation is required. When available, title is the stored trace title, typically generated after the first assistant reply. Manual title updates override auto-title.

List Traces

List traces with filtering and pagination.

GET /v1/traces

Query Parameters

Parameter	Type	Description
`brain_id`	string	Filter by brain ID
`receptor_id`	string	Filter by receptor ID
`user_id`	string	Filter by user ID
`search`	string	Search in trace_id and metadata.title
`created_after`	string	ISO date; filter traces created after
`created_before`	string	ISO date; filter traces created before
`limit`	number	Max traces to return (default: 20)
`offset`	number	Pagination offset
`sort`	string	Sort field: `created_at`, `updated_at`, `message_count`
`order`	string	Sort order: `asc` or `desc`

Example Request

TypeScript
curl

const { traces, total } = await auvy.traces.list({
  limit: 20,
  offset: 0,
  sort: 'created_at',
  order: 'desc',
})

curl "https://api.auvy.ai/v1/traces?limit=20&sort=created_at&order=desc" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "traces": [
    {
      "id": "trace-uuid",
      "trace_id": "trace-id",
      "tenant_id": "workspace-uuid",
      "user_id": "user-uuid",
      "api_key_id": null,
      "synapse_id": "receptor-uuid",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:01Z",
      "message_count": 5,
      "cost_summary": {
        "total_cost_usd": 0.01,
        "total_tokens": 1000,
        "input_tokens": 500,
        "output_tokens": 500
      }
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

Get Trace

Get a single trace by ID.

GET /v1/traces/:id

Path Parameters

Parameter	Type	Description
`id`	string	Trace ID

Example Request

TypeScript
curl

const { trace } = await auvy.traces.get('trace-id')

curl https://api.auvy.ai/v1/traces/trace-id \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "trace": {
    "id": "trace-id",
    "tenant_id": "tenant-uuid",
    "user_id": "user-uuid",
    "trace_id": "trace-id",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

Get trace messages

Returns serialized message documents for the trace (GET /v1/traces/:id/messages). Response shape includes content, roles, tool metadata, and ordering fields. The SDK method is traces.getEngrams().

GET /v1/traces/:id/messages

Path parameters

Parameter	Type	Description
`id`	string	Trace ID

Query parameters

Parameter	Type	Description
`limit`	number	Maximum number of engrams to return (default: unlimited)

Example request

TypeScript
curl

const { engrams } = await auvy.traces.getEngrams('trace-id')

const { engrams: page } = await auvy.traces.getEngrams('trace-id', {
  signal: abortController.signal,
})

curl "https://api.auvy.ai/v1/traces/trace-id/messages?limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "engrams": [
    {
      "id": "engram-uuid",
      "workspace_id": "workspace-uuid",
      "created_at": "2024-01-01T00:00:00Z",
      "content": { "type": "human", "content": "Hello" },
      "content_hash": "…",
      "metadata": {},
      "source_type": "user",
      "source_id": "user-uuid",
      "target_type": null,
      "target_id": null,
      "trace_id": "trace-id",
      "trace_type": "thread"
    }
  ]
}

Do not log raw engrams in untrusted environments; content can include rich structured data.

Add message to trace

Add a message to a trace. This will automatically create the trace if it doesn’t exist.

POST /v1/traces/:id/messages

Path Parameters

Parameter	Type	Description
`id`	string	Trace ID

Request Body

Field	Type	Required	Description
`content`	string	Yes	Message content (human turn; `source_type` is set from auth)
`metadata`	object	No	Additional metadata (e.g., `content_blocks`, tool call info)
`memory_ids`	array	No	Array of memory UUIDs to link to the trace

Example Request

TypeScript
curl

const { engram } = await auvy.traces.addMessage('trace-id', {
  content: 'Hello, AUVY!'
})

const { engram: withMemories } = await auvy.traces.addMessage('trace-id', {
  content: 'Analyze this document',
  memory_ids: ['memory-uuid-1', 'memory-uuid-2']
})

curl -X POST https://api.auvy.ai/v1/traces/trace-id/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, AUVY!",
    "memory_ids": ["memory-uuid-1"]
  }'

Example Response

{
  "engram": {
    "id": "engram-uuid",
    "trace_id": "trace-id",
    "source_type": "user",
    "target_type": null,
    "content": { "type": "human", "content": "Hello, AUVY!" },
    "content_hash": "…",
    "metadata": {},
    "created_at": "2024-01-01T00:00:00Z"
  }
}

Public Trace Access

Traces can be accessed via share tokens for public access without requiring full authentication.

Get Public Trace

Get a trace using a share token.

GET /v1/public/traces/:trace_id

Path Parameters

Parameter	Type	Description
`trace_id`	string	Trace ID

Query Parameters

Parameter	Type	Description
`t`	string	Share token (required)
`workspace`	string	Workspace slug (use with `receptor` for slug-based share)
`receptor`	string	Receptor slug (use with `workspace` for slug-based share)
`receptor_id`	string	Receptor UUID (alternative to workspace + receptor, same `t`)

Example Request

TypeScript
curl

const { trace } = await auvy.public.getTrace('trace-id', 'share-token', 'receptor-slug')

curl "https://api.auvy.ai/v1/public/traces/trace-id?t=share-token&workspace=workspace-slug&receptor=receptor-slug" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Get public trace engrams

Get engrams for a trace using a share token. Uses GET /v1/traces/:trace_id/messages with share token query parameters. Either pass t + workspace + receptor, or t + receptor_id (same scoping as public receptor invoke and GET /v1/public/traces/:trace_id).

GET /v1/traces/:trace_id/messages

Path Parameters

Parameter	Type	Description
`trace_id`	string	Trace ID

Query Parameters

Parameter	Type	Description
`t`	string	Share token (required)
`workspace`	string	Workspace slug (with `receptor` for slug-based share)
`receptor`	string	Receptor slug (with `workspace` for slug-based share)
`receptor_id`	string	Receptor UUID (with `t` for id-based share)
`limit`	number	Maximum number of engrams (optional)

Example Request

TypeScript
curl

const { engrams } = await auvy.public.getTraceEngrams(
  'trace-id',
  'share-token',
  'receptor-slug',
)

curl "https://api.auvy.ai/v1/traces/trace-id/messages?t=share-token&workspace=workspace-slug&receptor=receptor-slug&limit=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Trace events (Lane A, SSE)

Server pushes trace-scoped events (e.g. transcript advances, run state) over SSE.

Access	URL	Auth
Dashboard / API key / JWT	`GET /v1/traces/:trace_id/events`	`Authorization` + `X-Brain-Id` when using session users
Receptor share (public chat)	`GET /v1/public/traces/:trace_id/events`	`t` + `workspace` + `receptor`, or `t` + `receptor_id` (same as transcript; see Public trace events)

The SDK’s auvy.traces.eventsStreamUrl(traceId, options) picks the right base path; for share links pass shareToken in options. Alternate route: with a valid share query, GET /v1/traces/:trace_id/events also authorizes the same t parameters via resolveTraceAccess (useful for clients that do not use the /v1/public/... prefix). The public chat UI uses the /v1/public/traces/.../events shape.

Trace Lifecycle

Traces follow a simple lifecycle:

Creation: Traces are automatically created when the first message is added
Engrams: Turns are stored as engrams and returned in API order
State: Trace state is maintained automatically through engrams
Retrieval: Traces and their engrams can be retrieved at any time

Integration with Receptors

Traces are created and managed when you invoke receptors with a trace_id. Advanced: the same invoke body may include neuron_task_options (validated like Invoke neuron); omit trace_type: "system" for normal chat so turns stay on the thread timeline.

const { receptor } = await auvy.receptors.get('my-workspace', 'my-receptor')
const { job_id } = await auvy.receptors.fire(receptor.id, {
  message: 'Hello',
  trace_id: 'trace-id',
})

const status = await auvy.jobs.getStatus(job_id)
const { engrams } = await auvy.traces.getEngrams('trace-id')

Document linking

Traces can be linked to document-lane resources for RAG (retrieval-augmented generation):

// Add message with document resource links
await auvy.traces.addMessage('trace-id', {
  content: 'What do you know about this?',
  memory_ids: ['resource-uuid-1', 'resource-uuid-2'],
})

Error Handling

Common error scenarios:

404 Not Found: Trace doesn’t exist
403 Forbidden: Insufficient permissions to access trace
400 Bad Request: Invalid trace ID format or missing required fields

Assets and Artifacts API — ingest and manage document-lane knowledge
Jobs, streaming, and errors - Stream agent-run responses
Activity API - View trace activity and engrams

​Traces API

​Overview

​List Traces

​Query Parameters

​Example Request

​Example Response

​Get Trace

​Path Parameters

​Example Request

​Example Response

​Get trace messages

​Path parameters

​Query parameters

​Example request

​Example response

​Add message to trace

​Path Parameters

​Request Body

​Example Request

​Example Response

​Public Trace Access

​Get Public Trace

​Path Parameters

​Query Parameters

​Example Request

​Get public trace engrams

​Path Parameters

​Query Parameters

​Example Request

​Trace events (Lane A, SSE)

​Trace Lifecycle

​Integration with Receptors

​Document linking

​Error Handling

​Related

Traces API

Overview

List Traces

Query Parameters

Example Request

Example Response

Get Trace

Path Parameters

Example Request

Example Response

Get trace messages

Path parameters

Query parameters

Example request

Example response

Add message to trace

Path Parameters

Request Body

Example Request

Example Response

Public Trace Access

Get Public Trace

Path Parameters

Query Parameters

Example Request

Get public trace engrams

Path Parameters

Query Parameters

Example Request

Trace events (Lane A, SSE)

Trace Lifecycle

Integration with Receptors

Document linking

Error Handling

Related