POST
/
v2
/
logs
/
trace
curl -X POST \
  "https://api.adaline.ai/v2/logs/trace" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "trace": {
      "startedAt": 1704067200000,
      "endedAt": 1704067260000,
      "name": "api_request",
      "status": "success",
      "referenceId": "req_456",
      "sessionId": "session_789"
    },
    "spans": [
      {
        "promptId": "prompt_123",
        "startedAt": 1704067200000,
        "endedAt": 1704067230000,
        "name": "llm_processing",
        "status": "success",
        "content": {
          "input": "Process this request",
          "output": "Request processed successfully"
        },
        "referenceId": "span_001"
      }
    ]
  }'

{
  "traceId": "trace_abc123def456",
  "spanIds": ["span_xyz789ghi012"]
}
​
header
string

All requests require a valid workspace API key passed in the Authorization header:

Authorization: Bearer YOUR_WORKSPACE_API_KEY

​
Parameters

​
projectId
string
required

The unique identifier of the project in Adaline.

​
trace
object
required

The trace object containing trace details.

​
trace.startedAt
number
required

Unix timestamp when the trace started.

​
trace.endedAt
number

Unix timestamp when the trace ended (current time if not provided).

​
trace.name
string
required

Name/identifier for the trace.

​
trace.status
string
required

Status of the trace (one of: “success”, “failure”, “pending”, “unknown”).

​
trace.referenceId
string

External reference ID for the trace (e.g., traceId in your application / system).

​
trace.sessionId
string

Session ID associated with the trace (e.g., sessionId or threadId in your application / system).

​
trace.attributes
object

Additional attributes for the trace.

​
trace.tags
array

Array of tags for categorization.

​
spans
array

Array of span objects to create with the trace.

​
Span Object Parameters

​
promptId
string

The unique identifier of the prompt in Adaline.

​
deploymentId
string

The deployment ID of the prompt in Adaline.

​
startedAt
number
required

Unix timestamp when the span started.

​
endedAt
number
required

Unix timestamp when the span ended.

​
name
string
required

Name/identifier for the span.

​
status
string
required

Status of the span (one of: “success”, “failure”, “unknown”).

​
content
string
required

The stringified JSON content of the span (max 1MB).

​
runEvaluation
boolean

Whether to run evaluation on this span.

​
parentReferenceId
string

Reference ID of the parent span.

​
referenceId
string

External reference ID for the span.

​
sessionId
string

Session ID associated with the span.

​
attributes
object

Additional attributes for the span.

​
tags
array

Array of tags for categorization.

​
events
array

Array of events that occurred during the span.

​
Response

​
traceId
string

The unique identifier of the created trace.

​
spanIds
array

Array of unique identifiers for the created spans.

curl -X POST \
  "https://api.adaline.ai/v2/logs/trace" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "trace": {
      "startedAt": 1704067200000,
      "endedAt": 1704067260000,
      "name": "api_request",
      "status": "success",
      "referenceId": "req_456",
      "sessionId": "session_789"
    },
    "spans": [
      {
        "promptId": "prompt_123",
        "startedAt": 1704067200000,
        "endedAt": 1704067230000,
        "name": "llm_processing",
        "status": "success",
        "content": {
          "input": "Process this request",
          "output": "Request processed successfully"
        },
        "referenceId": "span_001"
      }
    ]
  }'

{
  "traceId": "trace_abc123def456",
  "spanIds": ["span_xyz789ghi012"]
}

​
Trace Creation Validation Rules

  1. Time Validation: startedAt must be before endedAt (if provided)
  2. Span Time Validation: Each span’s startedAt must be before its endedAt
  3. Trace-Span Time Relationship: All spans must start after or at the trace’s startedAt
  4. Reference ID Uniqueness: All span referenceIds must be unique within the request
  5. Parent Reference Validation: Any parentReferenceId must reference another span’s referenceId in the same request
  6. Trace Reference Requirement: If any span has a referenceId, the trace must also have a referenceId

​
Best Practices

  1. Structured Logging: Use consistent naming conventions for traces and spans to enable better analysis.

  2. Reference IDs: Use meaningful reference IDs that can be tracked across your application for better debugging.

  3. Content Size Management: Monitor your content size to stay within the 1MB limit per span.

  4. Batch Operations: When possible, use the trace endpoint to create multiple spans in a single request.

  5. Time Accuracy: Ensure timestamps are accurate and represent the actual start/end times of operations.

  6. Meaningful Attributes: Use attributes and tags to add context that will be useful for analysis and debugging.

  7. Session Tracking: Use session IDs consistently to track user sessions across multiple traces.