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
| Parameter | Type | Required | Description |
|---|---|---|---|
input | string | Yes | The prompt or input sent to the model |
output | string | Yes | The model’s response |
model | string | No | Model identifier (e.g. gpt-4o, claude-sonnet-4-20250514) |
latency_ms | float | No | End-to-end latency in milliseconds |
tags | list[string] | No | Arbitrary tags for filtering |
token_usage | object | No | Token counts: prompt_tokens, completion_tokens, total_tokens |
metadata | object | No | Arbitrary key-value metadata |
custom_attributes | object | No | Custom structured attributes for filtering and grouping |
version | string | No | Prompt or model version string |
session_id | string | No | Group related traces into a session |
spans | list | No | Sub-operation spans with name, start/end timestamps, and attributes |
cost | float | No | Total cost in USD for this call |
tool_calls | list | No | Tool/function calls made during the trace |
status | string | No | "success" or "error" (default: "success") |
error | string | No | Error 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
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | int | 100 | Max traces to return (1-1000) |
status | string | — | Filter by "success" or "error" |
start_date | string | — | ISO 8601 datetime lower bound |
end_date | string | — | 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"
}