API Reference

The Nexus REST API lets you ingest traces and spans from any language or framework. Base URL: https://nexus.keylightdigital.dev

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

HTTP header

Authorization: Bearer nxs_a1b2c3d4...

Creating API keys

Go to Dashboard → API Keys
Click Create new key and give it a name
Copy the key — it is shown only once
Store it in your environment (e.g. NEXUS_API_KEY)

Security: Keys are stored as SHA-256 hashes. If you lose a key, revoke it and create a new one.

Rate Limits & Plan Limits

Limit	Free	Pro ($9/mo)
Traces / month	1,000	50,000
Agents	1	Unlimited
Trace retention	30 days	90 days
Email alerts	—	✓ (error / timeout)

429 Too Many Requests — trace limit reached:

{
  "error": "Monthly trace limit reached. Upgrade to Pro.",
  "limit": 1000,
  "current": 1001,
  "upgrade_url": "/dashboard/billing"
}

403 Forbidden — agent limit reached (Free plan):

{
  "error": "Free plan limited to 1 agent",
  "upgrade_url": "/dashboard/billing"
}

POST /api/v1/traces

Create a new trace. Agents are auto-created on first use.

Request

POST /api/v1/traces
Authorization: Bearer <key>
Content-Type: application/json

{
  "agent_id": "my-assistant",
  "name": "user-query-2026-04-06",
  "status": "running",
  "started_at": "2026-04-06T12:00:00Z",
  "ended_at": null,
  "metadata": { "user_id": "u_123" }
}

Response 201

{
  "trace_id": "f47ac10b-58cc-..."
}

Request fields

Field	Type	Required	Description
agent_id	string	Yes	Your agent's name. Auto-created on first use.
name	string	Yes	Human-readable trace name (e.g. the task or query).
status	string	Yes	`running` \| `success` \| `error` \| `timeout`
started_at	string	Yes	ISO 8601 timestamp (e.g. `2026-04-06T12:00:00Z`).
ended_at	string \| null	No	ISO 8601 end timestamp. Set when trace completes.
metadata	object \| null	No	Arbitrary JSON. Stored and displayed in trace viewer.

Error responses

400 Invalid input — response includes {"error":"...", "fields":{"field":"reason"}}

401 Invalid or revoked API key

403 Agent limit reached (Free plan: 1 agent max)

429 Monthly trace limit reached (Free: 1,000/month)

POST /api/v1/traces/:id/spans

Add a span (sub-step) to a trace. Spans capture individual LLM calls, tool uses, or sub-agent invocations.

Request

POST /api/v1/traces/:trace_id/spans
Authorization: Bearer <key>
Content-Type: application/json

{
  "name": "llm-call",
  "status": "ok",
  "started_at": "2026-04-06T12:00:01Z",
  "ended_at": "2026-04-06T12:00:02Z",
  "input": { "prompt": "Summarize this..." },
  "output": { "text": "Here is a summary..." },
  "parent_span_id": null
}

Response 201

{
  "span_id": "a1b2c3d4-..."
}

Request fields

Field	Type	Required	Description
name	string	Yes	Span name (e.g. `llm-call`, `tool-use`).
status	string	Yes	`ok` \| `error`
started_at	string	Yes	ISO 8601 timestamp.
ended_at	string \| null	No	ISO 8601 end timestamp.
input	any \| null	No	Arbitrary JSON input (prompt, tool args, etc.).
output	any \| null	No	Arbitrary JSON output (model response, tool result, etc.).
error	string \| null	No	Error message string (set when status is `error`).
parent_span_id	string \| null	No	ID of parent span for nested waterfall display.

Error responses

400 Invalid input

401 Invalid or revoked API key

404 Trace not found or not owned by this API key

PATCH /api/v1/traces/:id

Finalize a trace. Used to update status and set ended_at when the trace completes.

Request

PATCH /api/v1/traces/:trace_id
Authorization: Bearer <key>
Content-Type: application/json

{
  "status": "success",
  "ended_at": "2026-04-06T12:00:05Z"
}

Response 200

{
  "ok": true
}

All fields are optional. Only provided fields are updated. Triggers email alert if status is error or timeout and user is on Pro plan.

TypeScript SDK

The official TypeScript/Node.js SDK wraps the REST API with a fluent interface.

Installation

terminal

npm install @keylightdigital/nexus

Quickstart

agent.ts

import { NexusClient } from '@keylightdigital/nexus'

const nexus = new NexusClient({
  apiKey: process.env.NEXUS_API_KEY,
  agentId: 'my-assistant',
})

const trace = await nexus.startTrace({ name: 'user-query' })

// Add a span for each step
await trace.addSpan({
  name: 'llm-call',
  input: { prompt },
  output: { text: response },
})

// Finalize the trace
await trace.end({ status: 'success' })

Configuration options

Option	Type	Required	Default
apiKey	string	Yes	—
agentId	string	Yes	—
baseUrl	string	No	`https://nexus.keylightdigital.dev`

Source: github.com/scobb/nexus/sdk

Python SDK

The Python SDK mirrors the TypeScript API and uses only the standard library — no extra dependencies.

Installation

terminal

pip install keylightdigital-nexus

Quickstart

agent.py

import os
from nexus_agent import NexusClient

nexus = NexusClient(
    api_key=os.environ["NEXUS_API_KEY"],
    agent_id="my-assistant",
)

trace = nexus.start_trace(name="user-query")

# Add a span for each step
trace.add_span(
    name="llm-call",
    input={"prompt": prompt},
    output={"text": response},
)

# Finalize the trace
trace.end(status="success")

Configuration options

Parameter	Type	Required	Default
api_key	str	Yes	—
agent_id	str	Yes	—
base_url	str	No	`https://nexus.keylightdigital.dev`

Source: github.com/scobb/nexus/sdk-python

Quick Start Examples

Ready-to-run example projects are available on GitHub at scobb/nexus-examples. Clone the repo and run any example in under 2 minutes.

Node.js / TypeScript

Multi-step agent with trace + span creation, error handling

Python

Sync + async patterns, realistic agent simulation

LangChain

NexusCallbackHandler for automatic LLM + tool tracing

clone and run

git clone https://github.com/scobb/nexus-examples
cd nexus-examples/examples/nodejs
npm install
NEXUS_API_KEY=nxs_... npm start

Ready to instrument your agents?

Start free

No credit card required. 1,000 traces/month free forever.