API Reference
Complete REST API reference for the Retrace platform.
Base URL
https://api.retraceai.techAll endpoints are versioned under /api/v1/. For local development, use http://localhost:3001.
Authentication
Two authentication methods are supported:
API Key — for SDKs, scripts, and server-to-server communication:
curl -H "x-retrace-key: rt_live_..." https://api.retraceai.tech/api/v1/tracesBearer Token — for the web application using Clerk-issued JWTs:
curl -H "Authorization: Bearer <jwt>" https://api.retraceai.tech/api/v1/tracesAll endpoints require authentication unless explicitly noted as public.
Traces
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/traces | Create a trace with optional batch spans |
| GET | /api/v1/traces | List traces (supports limit, offset, status params) |
| GET | /api/v1/traces/:id | Get a single trace with all child spans |
| DELETE | /api/v1/traces/:id | Delete a trace and all associated spans |
Tapes
Tapes are shareable, read-only snapshots of traces.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/tapes | Publish a trace as a shareable tape |
| GET | /api/v1/tapes/:slug | Get tape by slug (public, no auth required) |
| GET | /api/v1/tapes | List public tapes |
Embedding Tapes
Embed any public tape as an interactive player in your blog, docs, or README:
<iframe
src="https://retraceai.tech/embed/YOUR_TAPE_SLUG"
width="100%"
height="500"
frameborder="0"
style="border:1px solid #1a1b1e;border-radius:8px;"
allow="clipboard-write"
></iframe>The embed player includes:
- Auto-play controls with speed adjustment (0.5x–4x)
- Timeline visualization with span-type coloring
- Input/output display for each step
- "Powered by Retrace" attribution with link
To get the embed code, click the Embed button on any public tape page (/t/your-slug).
Forks
Forks let you branch from any span and replay with modifications.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/forks | Create a fork from a specific span |
| POST | /api/v1/forks/:id/replay | Execute a fork with modified parameters |
| GET | /api/v1/forks/:id/diff | Get the divergence diff between original and fork |
Memory
Persistent semantic memory for agents across sessions.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/memory | Store a memory entry |
| POST | /api/v1/memory/search | Semantic search across memories |
| GET | /api/v1/memory | List all memories (supports scope, category filters) |
| GET | /api/v1/memory/:id | Get a single memory by ID |
| DELETE | /api/v1/memory/:id | Delete a memory entry |
Search
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/search | Semantic search across all spans in your traces |
Accepts query (string) and optional limit (number, default 10).
API Keys
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/api-keys | Generate a new API key |
| GET | /api/v1/api-keys | Check if a key exists for the current user |
| DELETE | /api/v1/api-keys | Revoke the current API key |
Skills
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/skills | Create a skill |
| GET | /api/v1/skills | List skills (supports scope, tags filters) |
| GET | /api/v1/skills/:id | Get a skill by ID |
| PATCH | /api/v1/skills/:id | Update a skill (increments version) |
| DELETE | /api/v1/skills/:id | Delete a skill |
Billing
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/billing/checkout | Create a Dodo Payments checkout session |
| POST | /api/v1/billing/portal | Open the Dodo Payments customer portal |
Usage
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/usage | Get current month's usage and plan limits |
| GET | /api/v1/usage/daily | Get daily usage breakdown for last 30 days |
Evaluations
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/evaluations | Create an evaluation with criteria |
| GET | /api/v1/evaluations | List evaluations |
| GET | /api/v1/evaluations/:id | Get evaluation with run history |
| POST | /api/v1/evaluations/:id/run | Run evaluation against a trace |
| DELETE | /api/v1/evaluations/:id | Delete an evaluation |
Collaboration
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/comments | Add a comment to a trace or span |
| GET | /api/v1/comments | List comments for a trace (?trace_id=) |
| POST | /api/v1/assignments | Assign a trace to a team member |
| GET | /api/v1/assignments | List assignments for current user |
| GET | /api/v1/notifications | List notifications (last 50) |
| PATCH | /api/v1/notifications/read | Mark all notifications as read |
Explore (Public)
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/tapes/explore | Browse public tapes (no auth required) |
Supports sort (trending/newest/popular), tag, featured, limit, offset params.
Rate Limits
Rate limits are applied per authenticated user (keyed by the real client IP for unauthenticated routes):
| Endpoint class | Limit |
|---|---|
| Write endpoints | 100 req/min |
| Read endpoints | 300 req/min |
| AI-backed endpoints (root-cause, AI chat) | lower per-route caps apply |
Rate-limited responses return HTTP 429 with a Retry-After header indicating seconds until the next allowed request.
Error Format
All errors return a consistent JSON structure:
{ "error": "Human-readable error message" }| Status Code | Meaning |
|---|---|
| 400 | Bad request — invalid parameters or body |
| 401 | Unauthorized — missing or invalid credentials |
| 404 | Not found — resource does not exist |
| 429 | Rate limited — too many requests |
| 500 | Internal server error |
[!TIP] Use the
x-request-idresponse header when reporting issues. It helps the team locate your request in server logs.
Prompts
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/prompts | List all prompts |
| POST | /api/v1/prompts | Create a prompt with initial version |
| GET | /api/v1/prompts/:id | Get prompt with all versions |
| POST | /api/v1/prompts/:id/versions | Create a new version |
| DELETE | /api/v1/prompts/:id | Delete prompt and all versions |
Datasets
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/datasets | List evaluation datasets |
| POST | /api/v1/datasets | Create a dataset |
| GET | /api/v1/datasets/:id | Get dataset with items |
| POST | /api/v1/datasets/:id/items | Add trace or manual input to dataset |
| DELETE | /api/v1/datasets/:id | Delete dataset |
Insights
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/insights/drift?project_id=... | Detect metric drift (cost, tokens, duration, error rate) |
| GET | /api/v1/insights/failures?project_id=... | Cluster failed traces by error pattern |
| GET | /api/v1/insights/anomalies?window_hours=6 | Detect cost/latency/error spikes and volume drops |
| POST | /api/v1/insights/root-cause | AI-powered root-cause analysis for failed traces |
Anomaly Detection
Returns active anomalies with severity levels (low, medium, high, critical):
curl -H "x-retrace-key: rt_live_..." \
"https://api.retraceai.tech/api/v1/insights/anomalies?window_hours=6"Response:
{
"anomalies": [
{ "type": "cost_spike", "severity": "high", "metric": "avg_cost_per_trace", "baseline": 0.002, "current": 0.008, "changePercent": 300 }
],
"window_hours": 6,
"baseline_traces": 150,
"recent_traces": 42
}Root-Cause Analysis
Sends trace data to Gemini for automated failure explanation:
curl -X POST -H "x-retrace-key: rt_live_..." \
-H "Content-Type: application/json" \
-d '{"traceId": "uuid"}' \
"https://api.retraceai.tech/api/v1/insights/root-cause"Response:
{
"traceId": "...",
"traceName": "my-agent",
"analysis": {
"root_cause": "OpenAI API returned 429 rate limit on the third tool call",
"failed_step": "tool_call: search_web",
"contributing_factors": ["No retry logic", "Burst of 5 concurrent calls"],
"suggested_fix": "Add exponential backoff retry to tool calls",
"confidence": 0.92
}
}Analytics
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/analytics/costs | Cost breakdown (total, by model, daily time series) |
| GET | /api/v1/analytics/cost-intelligence | Cost-per-feature, model efficiency, optimization recommendations |
Cost Intelligence
Returns actionable cost optimization insights:
curl -H "x-retrace-key: rt_live_..." \
"https://api.retraceai.tech/api/v1/analytics/cost-intelligence"Response:
{
"byFeature": [
{ "name": "my-agent", "avgCost": 0.0045, "totalCost": 12.50, "count": 2778, "avgDuration": 3200 }
],
"modelEfficiency": [
{ "model": "gpt-4o", "avgCostPerCall": 0.012, "avgTokens": 1500, "avgDuration": 2100, "count": 500 }
],
"recommendations": [
{ "type": "model_downgrade", "priority": "medium", "message": "\"gpt-4o\" averages $0.0120/call. Consider a cheaper model for non-critical tasks.", "potential_savings": "$3.00/month" }
]
}Audit Logs
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/audit-logs/export | Bulk export audit logs (JSON or CSV) |
Supports query params: from (ISO datetime), to (ISO datetime), format (json or csv), limit (max 10000).
curl -H "x-retrace-key: rt_live_..." \
"https://api.retraceai.tech/api/v1/audit-logs/export?format=csv&from=2026-01-01T00:00:00Z"Feedback
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/v1/traces/:id/feedback | Submit thumbs up/down (+1/-1) with optional note |
| GET | /api/v1/traces/:id/feedback | Get your feedback for a trace |