API Reference

Public API

Send LLM execution traces from your agent and get back a permanent, shareable visual timeline. One POST call is all it takes.

endpointPOST https://tracen.nanocorp.app/api/traces

Getting Started

1

Create an account

2

Copy your API key

Go to /app/settings and copy your key. It looks like tracen_sk_...

3

Send your first trace

Include your key in the X-Tracen-Key header and POST a trace payload. You'll receive a shareable URL immediately.

Making Your First API Call

cURL

bash

curl -X POST https://tracen.nanocorp.app/api/traces \
  -H "Content-Type: application/json" \
  -H "X-Tracen-Key: tracen_sk_YOUR_KEY_HERE" \
  -d '{
    "prompt": "Summarise this text: ...",
    "response": "Here is a summary: ...",
    "provider": "openai",
    "model": "gpt-4o",
    "steps": [
      {
        "name": "llm_call",
        "timestamp": "2024-01-15T10:30:00.000Z",
        "latency_ms": 1240
      }
    ],
    "input_tokens": 120,
    "output_tokens": 45,
    "total_latency_ms": 1240,
    "status": "success",
    "error_message": null
  }'

JavaScript — fetch

javascript

const res = await fetch('https://tracen.nanocorp.app/api/traces', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Tracen-Key': 'tracen_sk_YOUR_KEY_HERE',
  },
  body: JSON.stringify({
    prompt: 'Summarise this text: ...',
    response: 'Here is a summary: ...',
    provider: 'openai',
    model: 'gpt-4o',
    steps: [
      {
        name: 'llm_call',
        timestamp: new Date().toISOString(),
        latency_ms: 1240,
      },
    ],
    input_tokens: 120,
    output_tokens: 45,
    total_latency_ms: 1240,
    status: 'success',
    error_message: null,
  }),
});

const { trace_id, url } = await res.json();
// url → https://tracen.nanocorp.app/traces/<trace_id>

API Response

On success the API returns HTTP 200 with:

json

{
  "trace_id": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://tracen.nanocorp.app/traces/550e8400-e29b-41d4-a716-446655440000"
}

The url is a permanent public page — no login required to view it. Format: https://tracen.nanocorp.app/traces/{id}

Payload Reference

Top-level fields

Field	Type	Required	Description
prompt	string	✓ yes	The input sent to the LLM
response	string	✓ yes	The output returned by the LLM (can be empty string)
provider	string	✓ yes	LLM provider: openai · anthropic · mistral · gemini · custom
model	string	✓ yes	Model identifier, e.g. gpt-4o or claude-3-5-sonnet-20241022
steps	array	✓ yes	Ordered list of execution steps (see Step object below)
input_tokens	integer \| null	optional	Token count for the prompt
output_tokens	integer \| null	optional	Token count for the response
total_latency_ms	integer \| null	optional	End-to-end wall-clock time in milliseconds
status	string	✓ yes	"success" or "error"
error_message	string \| null	optional	Error details when status is "error"

Step object (each item in steps)

Field	Type	Required	Description
name	string	✓ yes	Human-readable step label, e.g. "llm_call" or "tool_use"
timestamp	string	✓ yes	ISO-8601 datetime when this step started
latency_ms	integer	✓ yes	Duration of this step in milliseconds

Rate Limiting

Limit

100 req / hour

Scope

Per API key

Reset

Rolling window

Response

HTTP 429

When the limit is exceeded the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait before retrying.

Ready to start tracing?

Get Started