Skip to main content
POST
/
api
/
v1
/
traces
Create/Update Trace
curl --request POST \
  --url https://app.artanis.ai/api/v1/traces \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "trace_id": "<string>",
  "name": "<string>",
  "timestamp": "<string>",
  "status": "<string>",
  "duration_ms": 123,
  "metadata": {}
}
'
{
  "status": "<string>"
}

​
Overview

The /api/v1/traces endpoint manages the lifecycle of traces. You’ll call this endpoint twice per trace:
  1. Start: Create a trace with status: "running"
  2. Complete: Update the trace with status: "completed" and duration
Traces represent individual AI operations (e.g., answering a question, classifying text). Each trace has a unique client-generated ID.

​
Request Body

​
trace_id
string
required
Unique identifier for the trace. Must start with trace_ followed by 22 alphanumeric characters.Generate this client-side using a cryptographically secure random generator.Example: trace_a3f9c2e1b8d4f7a6c9e2
​
name
string
required
Human-readable operation name for filtering and grouping in the dashboard.Examples: "answer-question", "classify-ticket", "rag-query"
​
timestamp
string
required
ISO 8601 timestamp with milliseconds and UTC timezone.Format: YYYY-MM-DDTHH:mm:ss.sssZExample: "2025-12-22T10:30:45.123Z"Should represent when the operation started (same timestamp for both create and complete).
​
status
string
required
Trace status indicating current state.
  • "running" — Trace is in progress (use when creating)
  • "completed" — Trace is finished (use when completing)
​
duration_ms
integer
Duration of the operation in milliseconds.Required when status is "completed".Calculate as: (end_time - start_time) * 1000Example: 1234
​
metadata
object
Optional key-value pairs for filtering and searching traces in the dashboard.Common fields:
  • user_id — User who initiated the operation
  • session_id — Session identifier
  • environment — Production, staging, etc.
  • model — AI model version
  • version — Application version
All values must be JSON-serializable.

​
Response

​
status
string
Response status indicator.Returns "accepted" when the request is successfully queued.
The API uses a fire-and-forget pattern. A 202 Accepted response means the request was received and queued, not that validation passed.

​
Trace ID Generation

Trace IDs must be generated client-side to enable the fire-and-forget pattern. Format: trace_ + 22 random alphanumeric characters 
TRACE_ID="trace_$(openssl rand -hex 11)"
echo $TRACE_ID
# Output: trace_a3f9c2e1b8d4f7a6c9e2
Use cryptographically secure random generators. Don’t use predictable patterns or sequential IDs.

​
Usage Examples

​
Creating a Trace

# Generate unique trace ID
TRACE_ID="trace_$(openssl rand -hex 11)"
START_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%S.%3NZ")

curl -X POST https://app.artanis.ai/api/v1/traces \
  -H "Authorization: Bearer ak_..." \
  -H "Content-Type: application/json" \
  -d "{
    \"trace_id\": \"$TRACE_ID\",
    \"name\": \"answer-question\",
    \"timestamp\": \"$START_TIMESTAMP\",
    \"status\": \"running\",
    \"metadata\": {
      \"user_id\": \"user-123\",
      \"session_id\": \"session-456\"
    }
  }"

​
Completing a Trace

import time

start_time = time.time()

# ... your operation logic ...

duration_ms = int((time.time() - start_time) * 1000)

response = requests.post(
    "https://app.artanis.ai/api/v1/traces",
    headers={
        "Authorization": "Bearer ak_...",
        "Content-Type": "application/json"
    },
    json={
        "trace_id": trace_id,
        "name": "answer-question",
        "timestamp": timestamp,  # Original start timestamp
        "status": "completed",
        "duration_ms": duration_ms,
        "metadata": {
            "user_id": "user-123",
            "session_id": "session-456"
        }
    }
)
Use the same trace_id, name, timestamp, and metadata for both create and complete requests. Only status and duration_ms should change.

​
Metadata Best Practices

FieldExampleUse Case
user_id"user-123"Filter traces by user
session_id"session-456"Group related operations
environment"production"Separate prod/staging
model"gpt-4"Compare model performance
version"v2.3.1"Track changes over time
customer"acme-corp"Multi-tenant filtering
Keep metadata concise. Don’t include large objects or sensitive information — use state observations for detailed context.

​
Error Responses

Status CodeErrorSolution
400Invalid request formatCheck JSON syntax and required fields
401Invalid API keyVerify your API key is correct
413Trace metadata too largeReduce metadata size (< 100KB recommended)
429Rate limit exceededImplement exponential backoff retry

​
Next Steps

Observations Endpoint

Record inputs, outputs, and state for your trace

Complete Example

See a full end-to-end workflow