POST
/
v2
/
logs
/
span
curl -X POST \
  "https://api.adaline.ai/v2/logs/span" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "span": {
      "traceReferenceId": "req_456",
      "startedAt": 1704067230000,
      "endedAt": 1704067250000,
      "name": "post_processing",
      "status": "success",
      "content": {
        "action": "cleanup",
        "result": "success"
      }
    }
  }'

// Missing or invalid parameters
{
  "error": "No project found, projectId: project_123"
}

{
  "error": "startedAt must be before endedAt"
}

{
  "error": "No prompt found, promptId: prompt_123"
}

{
  "error": "Log trace already exists with referenceId: trace_456"
}

{
  "error": "Workspace 'workspace_123' has reached the limit of 100 log writes per month. Please upgrade your plan or contact support."
}
​
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.

​
span
object
required

The span object containing span details.

​
span.traceId
string

The ID of an existing trace (required if traceReferenceId not provided).

​
span.traceReferenceId
string

The reference ID of an existing trace (required if traceId not provided).

​
span.promptId
string

The unique identifier of the prompt used.

​
span.deploymentId
string

The deployment ID used for this span.

​
span.startedAt
number
required

Unix timestamp when the span started.

​
span.endedAt
number
required

Unix timestamp when the span ended.

​
span.name
string
required

Name/identifier for the span.

​
span.status
string
required

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

​
span.content
string
required

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

​
span.runEvaluation
boolean

Whether to run evaluation on this span.

​
span.parentReferenceId
string

Reference ID of the parent span.

​
span.referenceId
string

External reference ID for the span.

​
span.sessionId
string

Session ID associated with the span.

​
span.attributes
object

Additional attributes for the span.

​
span.tags
array

Array of tags for categorization.

​
span.events
array

Array of events that occurred during the span.

​
Response

​
spanId
array

Array of unique identifiers for the created span.

curl -X POST \
  "https://api.adaline.ai/v2/logs/span" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "span": {
      "traceReferenceId": "req_456",
      "startedAt": 1704067230000,
      "endedAt": 1704067250000,
      "name": "post_processing",
      "status": "success",
      "content": {
        "action": "cleanup",
        "result": "success"
      }
    }
  }'

​
Span Creation Validation Rules

  1. Trace Association: Either traceId or traceReferenceId must be provided
  2. Time Validation: startedAt must be before endedAt
  3. Content Size: Content must not exceed 1MB when serialized to JSON
// Missing or invalid parameters
{
  "error": "No project found, projectId: project_123"
}

{
  "error": "startedAt must be before endedAt"
}

{
  "error": "No prompt found, promptId: prompt_123"
}

{
  "error": "Log trace already exists with referenceId: trace_456"
}

{
  "error": "Workspace 'workspace_123' has reached the limit of 100 log writes per month. Please upgrade your plan or contact support."
}

​
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.