PATCH
/
v2
/
logs
/
update-log
# Update trace status and add completion metadata
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "conv_456",
    "logTrace": {
      "status": "success",
      "endedAt": 1704067280000,
      "attributes": [
        {
          "operation": "create",
          "key": "totalProcessingTime",
          "value": 80000
        },
        {
          "operation": "create",
          "key": "finalStatus",
          "value": "completed"
        },
        {
          "operation": "delete",
          "key": "tempProcessingData"
        }
      ],
      "tags": [
        {
          "operation": "create",
          "tag": "processed"
        },
        {
          "operation": "create",
          "tag": "validated"
        },
        {
          "operation": "delete",
          "tag": "pending"
        }
      ]
    }
  }'

# Update only trace status
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "traceId": "trace_abc123def456",
    "logTrace": {
      "status": "failure",
      "attributes": [
        {
          "operation": "create",
          "key": "errorReason",
          "value": "network_timeout"
        }
      ]
    }
  }'

# Clean up attributes only
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "trace_cleanup_001",
    "logTrace": {
      "attributes": [
        {
          "operation": "delete",
          "key": "debugData"
        },
        {
          "operation": "delete",
          "key": "temporaryResults"
        },
        {
          "operation": "create",
          "key": "cleanedAt",
          "value": 1704067300000
        }
      ]
    }
  }'

# Add tags for categorization
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "trace_categorize_001",
    "logTrace": {
      "tags": [
        {
          "operation": "create",
          "tag": "high_priority"
        },
        {
          "operation": "create",
          "tag": "customer_facing"
        },
        {
          "operation": "create",
          "tag": "production"
        }
      ]
    }
  }'
​
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.

​
traceId
string

The unique identifier of the trace to update (required if referenceId not provided).

​
referenceId
string

The reference ID of the trace to update (required if traceIdnot provided).

​
logTrace
object
required

The trace update object containing fields to modify.

​
logTrace.status
string

New status of the trace (one of: “success”, “failure”, “pending”, “unknown”)

​
logTrace.endedAt
number

Unix timestamp when the trace ended

​
logTrace.attributes
array

Array of attribute operations to perform (max 10 operations).

​
logTrace.tags
array

Array of tag operations to perform (max 10 operations).

​
Attribute Operations

Each attribute operation in the attributes array must specify an operation type:

​
operation
string
required

Either “create” or “delete”.

​
key
string
required

The attribute key.

​
value
string/number/boolean

The attribute value (required for “create” operation).

​
Tag Operations

Each tag operation in the tags array must specify an operation type:

​
operation
string
required

Either “create” or “delete”.

​
tag
string
required

The tag value.

​
Response

​
success
boolean

Indicates if the update was successful.

# Update trace status and add completion metadata
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "conv_456",
    "logTrace": {
      "status": "success",
      "endedAt": 1704067280000,
      "attributes": [
        {
          "operation": "create",
          "key": "totalProcessingTime",
          "value": 80000
        },
        {
          "operation": "create",
          "key": "finalStatus",
          "value": "completed"
        },
        {
          "operation": "delete",
          "key": "tempProcessingData"
        }
      ],
      "tags": [
        {
          "operation": "create",
          "tag": "processed"
        },
        {
          "operation": "create",
          "tag": "validated"
        },
        {
          "operation": "delete",
          "tag": "pending"
        }
      ]
    }
  }'

# Update only trace status
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "traceId": "trace_abc123def456",
    "logTrace": {
      "status": "failure",
      "attributes": [
        {
          "operation": "create",
          "key": "errorReason",
          "value": "network_timeout"
        }
      ]
    }
  }'

# Clean up attributes only
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "trace_cleanup_001",
    "logTrace": {
      "attributes": [
        {
          "operation": "delete",
          "key": "debugData"
        },
        {
          "operation": "delete",
          "key": "temporaryResults"
        },
        {
          "operation": "create",
          "key": "cleanedAt",
          "value": 1704067300000
        }
      ]
    }
  }'

# Add tags for categorization
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "trace_categorize_001",
    "logTrace": {
      "tags": [
        {
          "operation": "create",
          "tag": "high_priority"
        },
        {
          "operation": "create",
          "tag": "customer_facing"
        },
        {
          "operation": "create",
          "tag": "production"
        }
      ]
    }
  }'

​
Validation Rules

  1. Trace Identification: Either traceId or referenceId must be provided (but not both)
  2. Required Fields: At least one field in logTrace must be provided for update
  3. Time Validation: If endedAt is provided, it must be after the original trace’s startedAt
  4. Attribute Operations Limit: Maximum of 10 attribute operations per request
  5. Tag Operations Limit: Maximum of 10 tag operations per request
  6. Attribute Values: For “create” operations, the value field is required and must be a string, number, or boolean
  7. Operation Types: Only “create” and “delete” operations are supported for attributes and tags
// 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."
}

​
Common Use Cases

​
1. Finalizing Trace Status

Update a trace from “pending” to final status after processing completes:

JavaScript
await updateLogTrace("project_123", null, "trace_ref_001", {
  status: "success",
  endedAt: Date.now(),
  attributes: [
    {
      operation: "create",
      key: "completionTime",
      value: Date.now(),
    },
  ],
});

​
2. Error Handling

Mark a trace as failed and add error information:

JavaScript
await updateLogTrace("project_123", "trace_id_123", null, {
  status: "failure",
  endedAt: Date.now(),
  attributes: [
    {
      operation: "create",
      key: "errorCode",
      value: "PROCESSING_ERROR",
    },
    {
      operation: "create",
      key: "errorMessage",
      value: "Failed to process due to invalid input",
    },
  ],
  tags: [
    {
      operation: "create",
      tag: "error",
    },
  ],
});

​
3. Adding Metrics

Add performance metrics after processing:

Python
update_log_trace(
    'project_123',
    reference_id='perf_trace_001',
    log_trace={
        'attributes': [
            {
                'operation': 'create',
                'key': 'responseTime',
                'value': 1.25
            },
            {
                'operation': 'create',
                'key': 'tokensProcessed',
                'value': 500
            },
            {
                'operation': 'create',
                'key': 'qualityScore',
                'value': 0.92
            }
        ]
    }
)

​
4. Cleanup Temporary Data

Remove temporary attributes that are no longer needed:

cURL
curl -X PATCH \
  "https://api.adaline.ai/v2/logs/update-log" \
  -H "Authorization: Bearer your_workspace_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "project_123",
    "referenceId": "cleanup_trace_001",
    "logTrace": {
      "attributes": [
        {
          "operation": "delete",
          "key": "tempData"
        },
        {
          "operation": "delete",
          "key": "debugInfo"
        }
      ]
    }
  }'

​
Best Practices

  1. Use Reference IDs: Prefer using referenceId over traceId when you have meaningful external identifiers from your application.

  2. Batch Updates: Combine multiple attribute and tag operations in a single request to reduce API calls.

  3. Final Status Updates: Always update the trace status to a final state (“success”, “failure”) when processing completes.

  4. Add Completion Metadata: Include relevant completion metrics like processing time, quality scores, or record counts.

  5. Error Documentation: When marking traces as failed, include error codes and messages for debugging.

  6. Cleanup Temporary Data: Remove debugging or temporary attributes after processing to keep trace data clean.

  7. Consistent Tagging: Use consistent tag naming conventions for better categorization and filtering.

  8. Time Accuracy: Ensure endedAt timestamps accurately reflect when processing actually completed.

  9. Meaningful Attributes: Add attributes that provide valuable context for analysis and troubleshooting.

  10. Validate Before Update: Ensure trace exists and is accessible before attempting updates to avoid errors.