Traces
Retrieve trace
GET
/
api
/
traces
/
{trace_unique_id}
/
Get trace details
curl --request GET \
--url https://api.keywordsai.co/api/traces/{trace_unique_id}/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.keywordsai.co/api/traces/{trace_unique_id}/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.keywordsai.co/api/traces/{trace_unique_id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.keywordsai.co/api/traces/{trace_unique_id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.keywordsai.co/api/traces/{trace_unique_id}/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.keywordsai.co/api/traces/{trace_unique_id}/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.keywordsai.co/api/traces/{trace_unique_id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "trace_abc123",
"trace_unique_id": "trace_abc123",
"start_time": "2024-01-15T10:30:00Z",
"end_time": "2024-01-15T10:30:02.5Z",
"duration": 2.5,
"span_count": 3,
"llm_call_count": 2,
"total_prompt_tokens": 150,
"total_completion_tokens": 75,
"total_tokens": 225,
"total_cost": 0.00345,
"error_count": 0,
"metadata": {"user_id": "user123"},
"customer_identifier": "user@example.com",
"environment": "production",
"span_tree": [
{
"id": "span_1",
"span_unique_id": "span_1",
"span_name": "chat_completion",
"span_parent_id": null,
"log_type": "CHAT",
"timestamp": "2024-01-15T10:30:02Z",
"start_time": "2024-01-15T10:30:00Z",
"latency": 2.0,
"trace_unique_id": "trace_abc123",
"input": {
"messages": [{"role": "user", "content": "Explain quantum computing"}],
"model": "gpt-4",
"temperature": 0.7
},
"output": {
"id": "chatcmpl-abc123",
"choices": [
{
"message": {"role": "assistant", "content": "Quantum computing is a revolutionary technology..."},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 50, "completion_tokens": 75, "total_tokens": 125}
},
"model": "gpt-4",
"prompt_tokens": 50,
"completion_tokens": 75,
"cost": 0.00345,
"status": "success",
"status_code": 200,
"children": [
{
"span_unique_id": "span_2",
"span_name": "tool_call",
"span_parent_id": "span_1",
"log_type": "FUNCTION",
"start_time": "2024-01-15T10:30:00.5Z",
"timestamp": "2024-01-15T10:30:01Z",
"latency": 0.5,
"input": {"tool_name": "search", "query": "quantum computing basics"},
"output": {"results": ["Result 1", "Result 2"]},
"children": []
},
{
"span_unique_id": "span_3",
"span_name": "summarize",
"span_parent_id": "span_1",
"log_type": "TASK",
"start_time": "2024-01-15T10:30:01.5Z",
"timestamp": "2024-01-15T10:30:02Z",
"latency": 0.5,
"input": {"text": "Long text to summarize..."},
"output": {"summary": "Short summary"},
"children": []
}
]
}
]
}
Retrieves detailed information about a specific trace, including the complete span tree with full input/output for all spans.
Authentication
All endpoints require API key authentication:Authorization: Bearer YOUR_API_KEY
Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
trace_unique_id | string | Yes | Unique trace identifier |
Query Parameters (Optional)
| Parameter | Type | Description |
|---|---|---|
environment | string | Filter by environment |
timestamp | ISO 8601 | Exact timestamp of the trace |
start_time | ISO 8601 | Start of time range |
end_time | ISO 8601 | End of time range |
Examples
import requests
trace_id = "trace_abc123"
url = f"https://api.keywordsai.co/api/traces/{trace_id}/"
headers = {"Authorization": "Bearer YOUR_API_KEY"}
response = requests.get(url, headers=headers)
print(response.json())
curl -X GET "https://api.keywordsai.co/api/traces/trace_abc123/" \
-H "Authorization: Bearer YOUR_API_KEY"
Response
{
"id": "trace_abc123",
"trace_unique_id": "trace_abc123",
"start_time": "2024-01-15T10:30:00Z",
"end_time": "2024-01-15T10:30:02.5Z",
"duration": 2.5,
"span_count": 3,
"llm_call_count": 2,
"total_prompt_tokens": 150,
"total_completion_tokens": 75,
"total_tokens": 225,
"total_cost": 0.00345,
"error_count": 0,
"metadata": {"user_id": "user123"},
"customer_identifier": "user@example.com",
"environment": "production",
"span_tree": [
{
"id": "span_1",
"span_unique_id": "span_1",
"span_name": "chat_completion",
"span_parent_id": null,
"log_type": "CHAT",
"timestamp": "2024-01-15T10:30:02Z",
"start_time": "2024-01-15T10:30:00Z",
"latency": 2.0,
"trace_unique_id": "trace_abc123",
"input": {
"messages": [{"role": "user", "content": "Explain quantum computing"}],
"model": "gpt-4",
"temperature": 0.7
},
"output": {
"id": "chatcmpl-abc123",
"choices": [
{
"message": {"role": "assistant", "content": "Quantum computing is a revolutionary technology..."},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 50, "completion_tokens": 75, "total_tokens": 125}
},
"model": "gpt-4",
"prompt_tokens": 50,
"completion_tokens": 75,
"cost": 0.00345,
"status": "success",
"status_code": 200,
"children": [
{
"span_unique_id": "span_2",
"span_name": "tool_call",
"span_parent_id": "span_1",
"log_type": "FUNCTION",
"start_time": "2024-01-15T10:30:00.5Z",
"timestamp": "2024-01-15T10:30:01Z",
"latency": 0.5,
"input": {"tool_name": "search", "query": "quantum computing basics"},
"output": {"results": ["Result 1", "Result 2"]},
"children": []
},
{
"span_unique_id": "span_3",
"span_name": "summarize",
"span_parent_id": "span_1",
"log_type": "TASK",
"start_time": "2024-01-15T10:30:01.5Z",
"timestamp": "2024-01-15T10:30:02Z",
"latency": 0.5,
"input": {"text": "Long text to summarize..."},
"output": {"summary": "Short summary"},
"children": []
}
]
}
]
}
Span Tree Structure
Thespan_tree field contains an array of root-level spans. Each span can have nested children spans, forming a hierarchical tree structure.
Key Span Fields
| Field | Type | Description |
|---|---|---|
span_unique_id | string | Unique span identifier |
span_name | string | Name of the operation |
span_parent_id | string/null | Parent span ID (null for root) |
log_type | string | Span type (CHAT, COMPLETION, FUNCTION, TASK, etc.) |
start_time | datetime | When the span started |
timestamp | datetime | When the span ended |
latency | float | Duration in seconds |
input | object | Full span input |
output | object | Full span output |
model | string | Model used (for LLM spans) |
prompt_tokens | integer | Input tokens |
completion_tokens | integer | Output tokens |
cost | float | Cost in USD |
status | string | Status (success, error) |
status_code | integer | HTTP-like status code |
children | array | Nested child spans |
Error Responses
404 Not Found
{ "error": "Trace not found" }
401 Unauthorized
{ "detail": "Your API key is invalid or expired, please check your API key at https://platform.keywordsai.co/platform/api/api-keys" }
Was this page helpful?
⌘I
Get trace details
curl --request GET \
--url https://api.keywordsai.co/api/traces/{trace_unique_id}/ \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.keywordsai.co/api/traces/{trace_unique_id}/"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.keywordsai.co/api/traces/{trace_unique_id}/', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.keywordsai.co/api/traces/{trace_unique_id}/",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.keywordsai.co/api/traces/{trace_unique_id}/"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.keywordsai.co/api/traces/{trace_unique_id}/")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.keywordsai.co/api/traces/{trace_unique_id}/")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"id": "trace_abc123",
"trace_unique_id": "trace_abc123",
"start_time": "2024-01-15T10:30:00Z",
"end_time": "2024-01-15T10:30:02.5Z",
"duration": 2.5,
"span_count": 3,
"llm_call_count": 2,
"total_prompt_tokens": 150,
"total_completion_tokens": 75,
"total_tokens": 225,
"total_cost": 0.00345,
"error_count": 0,
"metadata": {"user_id": "user123"},
"customer_identifier": "user@example.com",
"environment": "production",
"span_tree": [
{
"id": "span_1",
"span_unique_id": "span_1",
"span_name": "chat_completion",
"span_parent_id": null,
"log_type": "CHAT",
"timestamp": "2024-01-15T10:30:02Z",
"start_time": "2024-01-15T10:30:00Z",
"latency": 2.0,
"trace_unique_id": "trace_abc123",
"input": {
"messages": [{"role": "user", "content": "Explain quantum computing"}],
"model": "gpt-4",
"temperature": 0.7
},
"output": {
"id": "chatcmpl-abc123",
"choices": [
{
"message": {"role": "assistant", "content": "Quantum computing is a revolutionary technology..."},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 50, "completion_tokens": 75, "total_tokens": 125}
},
"model": "gpt-4",
"prompt_tokens": 50,
"completion_tokens": 75,
"cost": 0.00345,
"status": "success",
"status_code": 200,
"children": [
{
"span_unique_id": "span_2",
"span_name": "tool_call",
"span_parent_id": "span_1",
"log_type": "FUNCTION",
"start_time": "2024-01-15T10:30:00.5Z",
"timestamp": "2024-01-15T10:30:01Z",
"latency": 0.5,
"input": {"tool_name": "search", "query": "quantum computing basics"},
"output": {"results": ["Result 1", "Result 2"]},
"children": []
},
{
"span_unique_id": "span_3",
"span_name": "summarize",
"span_parent_id": "span_1",
"log_type": "TASK",
"start_time": "2024-01-15T10:30:01.5Z",
"timestamp": "2024-01-15T10:30:02Z",
"latency": 0.5,
"input": {"text": "Long text to summarize..."},
"output": {"summary": "Short summary"},
"children": []
}
]
}
]
}