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 AI agents
Execution Tracking: Following the execution flow of receptors, neurons, and pathways
Message History: Storing and retrieving conversation messages
State Management: Maintaining context across multiple interactions

Traces are automatically created when the first message is added via engrams. No explicit creation is required.

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 (alias: `synapse_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
}

Note: Trace summaries include synapse_id for compatibility; engrams store receptor_id. Use receptor_id when filtering.

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

Get message history for a trace with pagination support.

GET /v1/traces/:id/messages

Path Parameters

Parameter	Type	Description
`id`	string	Trace ID

Query Parameters

Parameter	Type	Description
`limit`	number	Maximum number of messages to return (default: unlimited)
`cursor`	string	Cursor for pagination (optional)

Example Request

TypeScript
curl

// Get all messages
const { messages } = await auvy.traces.getMessages('trace-id')

// Get messages with limit
const { messages } = await auvy.traces.getMessages('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

{
  "messages": [
    {
      "id": "msg-uuid",
      "trace_id": "trace-id",
      "role": "user",
      "content": "Hello",
      "metadata": {},
      "created_at": "2024-01-01T00:00:00Z"
    },
    {
      "id": "msg-uuid-2",
      "trace_id": "trace-id",
      "role": "assistant",
      "content": "Hi there!",
      "metadata": {
        "content_blocks": []
      },
      "created_at": "2024-01-01T00:00:01Z"
    }
  ]
}

Message Roles

Messages support the following roles:

user - User messages
assistant - AI assistant responses
system - System messages
neuron - Messages from neuron executions

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
`role`	string	Yes	Message role: `user`, `assistant`, `system`, or `neuron`
`content`	string	Yes	Message content
`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

// Simple message
const { message } = await auvy.traces.addMessage('trace-id', {
  role: 'user',
  content: 'Hello, AUVY!'
})

// Message with memory links
const { message } = await auvy.traces.addMessage('trace-id', {
  role: 'user',
  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 '{
    "role": "user",
    "content": "Hello, AUVY!",
    "memory_ids": ["memory-uuid-1"]
  }'

Example Response

{
  "message": {
    "id": "msg-uuid",
    "trace_id": "trace-id",
    "role": "user",
    "content": "Hello, AUVY!",
    "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 (required)
`receptor`	string	Receptor slug (required)

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 Messages

Get messages for a trace using a share token. This endpoint uses /v1/traces/:trace_id/messages with share token authentication via query parameters.

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 (required)
`receptor`	string	Receptor slug (required)
`limit`	number	Maximum number of messages (optional)

Example Request

TypeScript
curl

const { messages } = await auvy.public.getTraceMessages(
  '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 Lifecycle

Traces follow a simple lifecycle:

Creation: Traces are automatically created when the first message is added
Messages: Messages are added sequentially to build conversation history
State: Trace state is maintained automatically through engrams
Retrieval: Traces and their messages can be retrieved at any time

Integration with Receptors

Traces are created and managed when you invoke receptors with a trace_id:

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

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

Memory Linking

Traces can be linked to memories for RAG (Retrieval-Augmented Generation):

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

// Memories are automatically linked to the trace's recollection

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

Memories API - Store persistent memories for traces
Recollections API - Manage trace recollections
Integration patterns - Stream receptor execution responses
Activity API - View trace activity and engrams

Core API

Automation API

Platform API

Traces

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

Message Roles

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 Messages

Path Parameters

Query Parameters

Example Request

Trace Lifecycle

Integration with Receptors

Memory Linking

Error Handling

Core API

Automation API

Platform API

​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

​Message Roles

​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 Messages

​Path Parameters

​Query Parameters

​Example Request

​Trace Lifecycle

​Integration with Receptors

​Memory 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

Message Roles

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 Messages

Path Parameters

Query Parameters

Example Request

Trace Lifecycle

Integration with Receptors

Memory Linking

Error Handling

Related