Skip to main content

​
Log a Trace

curl -X POST https://api.trainlyai.com/v1/{project_id}/traces \
  -H "Authorization: Bearer tk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Translate to French: Hello world",
    "output": "Bonjour le monde",
    "model": "gpt-4o",
    "latency_ms": 612.3,
    "tags": ["translation"],
    "token_usage": {
      "prompt_tokens": 18,
      "completion_tokens": 8,
      "total_tokens": 26
    },
    "status": "success"
  }'
POST /v1/{project_id}/traces

​
Request Body

ParameterTypeRequiredDescription
inputstringYesThe prompt or input sent to the model
outputstringYesThe model’s response
modelstringNoModel identifier (e.g. gpt-4o, claude-sonnet-4-20250514)
latency_msfloatNoEnd-to-end latency in milliseconds
tagslist[string]NoArbitrary tags for filtering
token_usageobjectNoToken counts: prompt_tokens, completion_tokens, total_tokens
metadataobjectNoArbitrary key-value metadata
custom_attributesobjectNoCustom structured attributes for filtering and grouping
versionstringNoPrompt or model version string
session_idstringNoGroup related traces into a session
spanslistNoSub-operation spans with name, start/end timestamps, and attributes
costfloatNoTotal cost in USD for this call
tool_callslistNoTool/function calls made during the trace
statusstringNo"success" or "error" (default: "success")
errorstringNoError message if status is "error"

​
Response

{
  "trace_id": "trc_9f8e7d6c5b4a",
  "status": "created"
}

​
List Traces

curl "https://api.trainlyai.com/v1/{project_id}/analytics/traces?limit=50&status=error&start_date=2026-04-01T00:00:00Z" \
  -H "Authorization: Bearer tk_your_api_key"
GET /v1/{project_id}/analytics/traces

​
Query Parameters

ParameterTypeDefaultDescription
limitint100Max traces to return (1-1000)
statusstring—Filter by "success" or "error"
start_datestring—ISO 8601 datetime lower bound
end_datestring—ISO 8601 datetime upper bound

​
Response

[
  {
    "trace_id": "trc_9f8e7d6c5b4a",
    "input": "Translate to French: Hello world",
    "output": "Bonjour le monde",
    "model": "gpt-4o",
    "latency_ms": 612.3,
    "status": "success",
    "tags": ["translation"],
    "token_usage": {
      "prompt_tokens": 18,
      "completion_tokens": 8,
      "total_tokens": 26
    },
    "cost": 0.00034,
    "created_at": "2026-04-07T14:23:01Z"
  }
]

​
Get Trace Details

curl "https://api.trainlyai.com/v1/{project_id}/analytics/traces/trc_9f8e7d6c5b4a" \
  -H "Authorization: Bearer tk_your_api_key"
GET /v1/{project_id}/analytics/traces/{trace_id}

​
Response

{
  "trace_id": "trc_9f8e7d6c5b4a",
  "input": "Translate to French: Hello world",
  "output": "Bonjour le monde",
  "model": "gpt-4o",
  "latency_ms": 612.3,
  "status": "success",
  "tags": ["translation"],
  "token_usage": {
    "prompt_tokens": 18,
    "completion_tokens": 8,
    "total_tokens": 26
  },
  "metadata": {},
  "custom_attributes": {},
  "version": "v1.2.0",
  "session_id": "sess_abc123",
  "cost": 0.00034,
  "tool_calls": [],
  "spans": [
    {
      "name": "llm_call",
      "start_ms": 0,
      "end_ms": 610,
      "attributes": { "provider": "openai" }
    }
  ],
  "created_at": "2026-04-07T14:23:01Z"
}