Traces API

Monitor and analyze AI agent execution traces with detailed message flows, token usage, costs, and performance metrics

GET

/tenants/{tenantId}/traces

Auth Required

List Traces

Retrieve a paginated list of activity traces

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace

Query Parameters

Name	Type	Description
page	`number`	Page number for pagination Default: `1`
per_page	`number`	Number of results per page Default: `20`
search	`string`	Search by prompt name or model

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/traces' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "data": [
    {
      "traceId": "trace_abc123",
      "promptName": "customer_support_agent",
      "status": "completed",
      "tags": ["production", "support"],
      "inputTokens": 250,
      "outputTokens": 1000,
      "totalTokens": 1250,
      "cost": 0.015,
      "duration": 5000,
      "modelConfig": {
        "model": "claude-3-5-sonnet-20241022",
        "provider": "anthropic",
        "temperature": 0.7
      },
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ],
  "page": 1,
  "per_page": 20,
  "has_more": false
}

GET

/tenants/{tenantId}/traces/{traceId}

Auth Required

Get Trace Details

Retrieve detailed information about a specific trace including all messages, tool calls, and execution metadata

Path Parameters

Name	Type	Description
tenantId Required	`string`	Unique identifier for the tenant workspace
traceId Required	`string`	Unique identifier for the trace

Examples

curl -X GET \
  'https://api.staging.agnt.ai/tenants/tenant_123/traces/trace_abc123' \
  -H 'Authorization: Bearer sk_live_your_service_key_here'

Response Example

200 OK

{
  "traceId": "trace_abc123",
  "promptName": "customer_support_agent",
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful customer support agent..."
    },
    {
      "role": "user",
      "content": "I need help with my order"
    },
    {
      "role": "assistant",
      "content": "I'd be happy to help with your order...",
      "tool_calls": [
        {
          "id": "call_1",
          "name": "search_orders",
          "args": {"query": "recent orders"}
        }
      ]
    },
    {
      "role": "tool",
      "content": "Found 3 recent orders...",
      "tool_call_id": "call_1"
    }
  ],
  "output": {
    "message": "I found your recent orders and can help you...",
    "success": true
  },
  "inputTokens": 250,
  "outputTokens": 1000,
  "totalTokens": 1250,
  "cost": 0.015,
  "costCurrency": "USD",
  "duration": 5000,
  "modelConfig": {
    "model": "claude-3-5-sonnet-20241022",
    "provider": "anthropic",
    "temperature": 0.7,
    "max_tokens": 2048
  },
  "tools": [
    {
      "name": "search_orders",
      "description": "Search customer orders",
      "parameters": {
        "type": "object",
        "properties": {
          "query": {"type": "string"}
        }
      },
      "metadata": {}
    }
  ],
  "toolChoice": "auto",
  "status": "completed",
  "tags": ["production", "support"],
  "metadata": {
    "customer_id": "cust_123",
    "session_id": "sess_456"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "timestamp": 1705318200000
}