API Reference

Interact with Opswald programmatically to manage traces, replay sessions, and integrate with your development workflow.

Authentication

All API requests require authentication via Bearer token:

curl -H "Authorization: Bearer ops_abc123..." https://api.opswald.com/v1/traces

Get your API key from app.opswald.com/settings/api.

Base URL

https://api.opswald.com/v1

Rate Limits

Plan	Requests/minute	Burst
Free	100	200
Pro	1,000	2,000
Teams	5,000	10,000
Enterprise	Custom	Custom

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1773754800

Traces API

List Traces

GET /v1/traces

Query Parameters:

limit (integer, 1-100): Number of traces to return (default: 50)
offset (integer): Skip this number of traces (default: 0)
start_time (ISO 8601): Filter traces after this time
end_time (ISO 8601): Filter traces before this time
error (boolean): Filter by error status
model (string): Filter by LLM model
min_cost (number): Minimum session cost in dollars
max_cost (number): Maximum session cost in dollars
user_id (string): Filter by user ID

Response:

{
  "traces": [
    {
      "id": "trace_abc123",
      "session_id": "session_456",
      "user_id": "user_789",
      "started_at": "2026-03-17T14:15:32Z",
      "ended_at": "2026-03-17T14:18:45Z",
      "duration_ms": 193000,
      "total_cost": 0.0245,
      "total_tokens": {
        "input": 1250,
        "output": 850
      },
      "models_used": ["gpt-4o", "claude-3-sonnet"],
      "steps": 12,
      "errors": 0,
      "status": "completed"
    }
  ],
  "total": 157,
  "has_more": true
}

Get Trace Details

GET /v1/traces/{trace_id}

Response:

{
  "id": "trace_abc123",
  "session_id": "session_456",
  "user_id": "user_789",
  "started_at": "2026-03-17T14:15:32Z",
  "ended_at": "2026-03-17T14:18:45Z",
  "duration_ms": 193000,
  "total_cost": 0.0245,
  "steps": [
    {
      "id": "step_001",
      "step_number": 1,
      "type": "user_input",
      "timestamp": "2026-03-17T14:15:32Z",
      "input": {
        "message": "Analyze this sales report",
        "attachments": ["sales-q1.csv"]
      },
      "duration_ms": 0,
      "cost": 0
    },
    {
      "id": "step_002",
      "step_number": 2,
      "type": "llm_call",
      "timestamp": "2026-03-17T14:15:33Z",
      "input": {
        "model": "gpt-4o",
        "messages": [
          {"role": "system", "content": "You are a data analyst..."},
          {"role": "user", "content": "Analyze this sales report"}
        ],
        "temperature": 0.1
      },
      "output": {
        "content": "I'll analyze the sales report. Let me start by examining the data...",
        "tool_calls": [
          {
            "function": "read_file",
            "arguments": {"filename": "sales-q1.csv"}
          }
        ]
      },
      "duration_ms": 2140,
      "cost": 0.0087,
      "tokens": {
        "input": 245,
        "output": 89
      }
    }
  ]
}

Delete Trace

DELETE /v1/traces/{trace_id}

Response:

{
  "deleted": true,
  "trace_id": "trace_abc123"
}

Replay API

Start Replay

POST /v1/replays

Request Body:

{
  "trace_id": "trace_abc123",
  "mode": "interactive",
  "modifications": {
    "model": "claude-3-sonnet",
    "temperature": 0.0
  },
  "fork_from_step": 5
}

Response:

{
  "replay_id": "replay_def456",
  "trace_id": "trace_abc123",
  "mode": "interactive",
  "status": "running",
  "url": "https://app.opswald.com/replays/replay_def456",
  "started_at": "2026-03-17T14:20:00Z"
}

Get Replay Status

GET /v1/replays/{replay_id}

Response:

{
  "replay_id": "replay_def456",
  "trace_id": "trace_abc123",
  "status": "completed",
  "current_step": 12,
  "total_steps": 12,
  "started_at": "2026-03-17T14:20:00Z",
  "completed_at": "2026-03-17T14:22:15Z",
  "result": {
    "final_output": "Analysis complete. Key findings: Revenue increased 15% QoQ...",
    "total_cost": 0.0198,
    "duration_ms": 135000,
    "changes_from_original": [
      {
        "step": 3,
        "field": "model",
        "original": "gpt-4o",
        "modified": "claude-3-sonnet"
      }
    ]
  }
}

Control Replay

POST /v1/replays/{replay_id}/control

Request Body:

{
  "action": "pause",
  "step": 8
}

Actions:

play - Resume replay
pause - Pause at current or specified step
step - Advance one step
jump - Jump to specific step number
stop - Terminate replay

Sessions API

List Sessions

GET /v1/sessions

Query Parameters:

limit (integer): Number of sessions to return
user_id (string): Filter by user
active (boolean): Filter by active status

Response:

{
  "sessions": [
    {
      "session_id": "session_456",
      "user_id": "user_789",
      "started_at": "2026-03-17T14:15:32Z",
      "last_activity": "2026-03-17T14:18:45Z",
      "status": "completed",
      "trace_count": 3,
      "total_cost": 0.067
    }
  ]
}

Get Session Details

GET /v1/sessions/{session_id}

End Session

POST /v1/sessions/{session_id}/end

Events API

Create Event

POST /v1/events

Request Body:

{
  "event_type": "llm_call",
  "session_id": "session_456",
  "data": {
    "model": "gpt-4o",
    "input": {
      "messages": [{"role": "user", "content": "Hello"}]
    },
    "output": {
      "content": "Hi there! How can I help you today?"
    },
    "cost": 0.0012,
    "tokens": {"input": 8, "output": 12}
  },
  "timestamp": "2026-03-17T14:15:32Z"
}

Response:

{
  "event_id": "evt_789",
  "processed": true,
  "trace_id": "trace_abc123"
}

Get Event

GET /v1/events/{event_id}

Analytics API

Usage Analytics

GET /v1/analytics/usage

Query Parameters:

period (string): “1d”, “7d”, “30d”, “90d”
group_by (string): “day”, “week”, “month”

Response:

{
  "period": "7d",
  "total_traces": 1247,
  "total_cost": 23.45,
  "total_tokens": 2847382,
  "daily": [
    {
      "date": "2026-03-17",
      "traces": 89,
      "cost": 3.21,
      "tokens": 287432
    }
  ],
  "top_models": [
    {"model": "gpt-4o", "usage": 0.64, "cost": 15.23},
    {"model": "claude-3-sonnet", "usage": 0.36, "cost": 8.22}
  ]
}

Cost Analytics

GET /v1/analytics/cost

Response:

{
  "total_cost": 145.32,
  "cost_by_model": {
    "gpt-4o": 89.21,
    "claude-3-sonnet": 56.11
  },
  "cost_by_user": {
    "user_123": 45.67,
    "user_456": 32.10
  },
  "trends": {
    "daily_average": 4.82,
    "weekly_growth": 0.12
  }
}

Golden Tests API

Create Golden Test

POST /v1/golden-tests

Request Body:

{
  "trace_id": "trace_abc123",
  "name": "Customer Support Flow",
  "description": "Complete customer issue resolution workflow",
  "tags": ["support", "critical"],
  "expected_outcome": {
    "status": "completed",
    "final_message": "Issue resolved successfully"
  }
}

Run Golden Tests

POST /v1/golden-tests/run

Request Body:

{
  "test_ids": ["test_123", "test_456"],
  "modifications": {
    "timeout": 60,
    "model": "gpt-4o"
  }
}

Response:

{
  "run_id": "run_789",
  "status": "running",
  "total_tests": 2,
  "url": "https://app.opswald.com/golden-tests/runs/run_789"
}

Webhooks API

Create Webhook

POST /v1/webhooks

Request Body:

{
  "url": "https://your-app.com/webhooks/opswald",
  "events": ["trace.completed", "trace.error"],
  "secret": "your-webhook-secret",
  "active": true
}

Webhook Events

Events sent to your webhook endpoint:

trace.completed

{
  "event": "trace.completed",
  "timestamp": "2026-03-17T14:18:45Z",
  "data": {
    "trace_id": "trace_abc123",
    "session_id": "session_456",
    "duration_ms": 193000,
    "total_cost": 0.0245,
    "status": "completed"
  }
}

trace.error

{
  "event": "trace.error",
  "timestamp": "2026-03-17T14:16:22Z",
  "data": {
    "trace_id": "trace_abc123",
    "session_id": "session_456",
    "error": {
      "type": "tool_error",
      "message": "Failed to send email: SMTP authentication failed",
      "step": 8
    }
  }
}

Error Responses

All errors follow this format:

{
  "error": {
    "type": "validation_error",
    "message": "Invalid trace_id format",
    "details": {
      "field": "trace_id",
      "expected": "UUID v4 format"
    }
  }
}

Error Types:

authentication_error (401) - Invalid API key
authorization_error (403) - Insufficient permissions
validation_error (400) - Invalid request data
not_found (404) - Resource not found
rate_limit_exceeded (429) - Too many requests
server_error (500) - Internal server error

SDKs

Official SDKs available for:

Python

pip install opswald

from opswald import OpsClient

client = OpsClient("your-api-key")
traces = client.traces.list(limit=10)

TypeScript/JavaScript

npm install opswald

import { OpsClient } from 'opswald';

const client = new OpsClient('your-api-key');
const traces = await client.traces.list({ limit: 10 });

Go

go get github.com/opswald/opswald-go

import "github.com/opswald/opswald-go"

client := opswald.NewClient("your-api-key")
traces, err := client.Traces.List(10)

Pagination

List endpoints support cursor-based pagination:

{
  "data": [...],
  "pagination": {
    "has_more": true,
    "next_cursor": "cursor_abc123"
  }
}

Use the cursor parameter for subsequent requests:

GET /v1/traces?cursor=cursor_abc123&limit=50