POST
/api/v1/traces/analyzeAnalyze a trace for issues
Runs TraceAssistant analysis. Body requires EITHER `traceId` OR `spans[]` (max 10,000). With `traceId`, `projectId` is ALSO required — 400 MISSING_PROJECT_ID without it — because the trace store is a process-wide singleton and the lookup must be pinned to your tenant; a traceId that resolves to no spans returns 400 NO_SPANS. With `spans[]` supplied directly, `projectId` is optional. `callLLM: false` selects rule-based quick mode; otherwise the full analysis calls the server-side LLM and degrades to the rule-based signal when no provider is configured. Requires `evals:read` and, when a projectId is given, membership on it.
Authentication
Send Authorization: Bearer YOUR_API_KEY on every request. Generate API keys at /dashboard/settings/api-keys.
Request body required
Example
{
"traceId": "string",
"spans": [
{
"spanId": "",
"operationName": "string",
"durationMs": 0,
"status": "ok",
"attributes": {},
"events": [
{
"name": "string",
"attributes": {}
}
]
}
],
"callLLM": false,
"projectId": "00000000-0000-0000-0000-000000000000"
}Schema
{
"application/json": {
"schema": {
"type": "object",
"properties": {
"traceId": {
"type": "string",
"maxLength": 200
},
"spans": {
"maxItems": 10000,
"type": "array",
"items": {
"type": "object",
"properties": {
"spanId": {
"default": "",
"type": "string",
"maxLength": 200
},
"operationName": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"durationMs": {
"type": "number",
"minimum": 0
},
"status": {
"default": "ok",
"type": "string",
"maxLength": 100
},
"attributes": {
"default": {},
"type": "object",
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
}
]
}
},
"events": {
"maxItems": 1000,
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 1000
},
"attributes": {
"default": {},
"type": "object",
"additionalProperties": {}
}
},
"required": [
"name",
"attributes"
],
"additionalProperties": false
}
}
},
"required": [
"spanId",
"operationName",
"durationMs",
"status",
"attributes"
],
"additionalProperties": {}
}
},
"callLLM": {
"type": "boolean",
"description": "Set false for rule-based quick mode."
},
"projectId": {
"type": "string",
"format": "uuid",
"pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
}
},
"additionalProperties": false
}
}
}Response
200 example
{
"success": true
}All status codes
200Analysis findings.
400(no description)
401(no description)
403Forbidden — the credential is valid but lacks the API-key scope, member role, or plan entitlement this operation requires.
429(no description)
500Internal Server Error — an unhandled error was converted to the standard error envelope (INTERNAL_ERROR).
Code samples
cURL
curl -X POST \
https://evalguard.ai/api/v1/traces/analyze \
-H "Authorization: Bearer $EVALGUARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "traceId": "string", "spans": [ { "spanId": "", "operationName": "string", "durationMs": 0, "status": "ok", "attributes": {}, "events": [ { "name": "string", "attributes": {} } ] } ], "callLLM": false, "projectId": "00000000-0000-0000-0000-000000000000" }'TypeScript
// The TypeScript SDK (@evalguard/sdk) exposes TYPED methods — eval,
// getEvalRun, securityScan, checkFirewall, … — not a generic request().
// For an arbitrary endpoint, call it directly:
const res = await fetch("https://evalguard.ai/api/v1/traces/analyze", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.EVALGUARD_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"traceId": "string",
"spans": [
{
"spanId": "",
"operationName": "string",
"durationMs": 0,
"status": "ok",
"attributes": {},
"events": [
{
"name": "string",
"attributes": {}
}
]
}
],
"callLLM": false,
"projectId": "00000000-0000-0000-0000-000000000000"
}),
});
console.log(res.status, await res.json());Python
# The Python SDK (pip install evalguardai) exposes TYPED methods on
# EvalGuardClient — run_eval, get_eval, … — not a generic request().
# For an arbitrary endpoint, call it directly:
import os
import requests
headers = {"Authorization": f"Bearer {os.environ['EVALGUARD_API_KEY']}"}
headers["Content-Type"] = "application/json"
response = requests.request(
"POST",
"https://evalguard.ai/api/v1/traces/analyze",
headers=headers,
json={
"traceId": "string",
"spans": [
{
"spanId": "",
"operationName": "string",
"durationMs": 0,
"status": "ok",
"attributes": {},
"events": [
{
"name": "string",
"attributes": {}
}
]
}
],
"callLLM": False,
"projectId": "00000000-0000-0000-0000-000000000000"
},
)
print(response.status_code, response.json())Go
package main
import (
"context"
"fmt"
"net/http"
"os"
"strings"
)
func main() {
body := strings.NewReader(`{"traceId":"string","spans":[{"spanId":"","operationName":"string","durationMs":0,"status":"ok","attributes":{},"events":[{"name":"string","attributes":{}}]}],"callLLM":false,"projectId":"00000000-0000-0000-0000-000000000000"}`)
req, _ := http.NewRequestWithContext(context.Background(), "POST", "https://evalguard.ai/api/v1/traces/analyze", body)
req.Header.Set("Authorization", "Bearer "+os.Getenv("EVALGUARD_API_KEY"))
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil { panic(err) }
defer resp.Body.Close()
fmt.Println(resp.Status)
}Errors
400401403429500