Skip to main content

Documentation Index

Fetch the complete documentation index at: https://whyops.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

While the WhyOps Proxy is the easiest way to instrument your agents automatically, you can send events directly to whyops-analyse when you need custom tools, non-LLM reasoning steps, or internal framework logic in the graph.

​
When to use manual events

Use manual events for anything the proxy cannot see by itself:
  • your actual tool execution input/output
  • retries inside your framework
  • orchestration steps outside the LLM boundary
  • runtime crashes after the LLM asked for a tool
  • internal thinking blocks or planning state you choose to expose

Manual Events Reference

Detailed event payload shapes, recommended runtime patterns, idempotency guidance, and tool pipeline examples.

SDK Runtime Guides

Use the published SDKs if you want the same event model with typed helpers instead of raw JSON payloads.

​
Endpoint Overview

Base URL: https://a.whyops.com/api (or your self-hosted URL) Authentication: You must include an API key generated from the WhyOps Dashboard in the Authorization header. 
Authorization: Bearer <WHYOPS_API_KEY>
The API key automatically resolves your userId, projectId, and environmentId. If you do not use API key auth, you must send all of these headers manually: 
X-User-Id: <uuid>
X-Project-Id: <uuid>
X-Environment-Id: <uuid>

​
Optional headers

You can optionally send X-External-User-Id to link traces to your application’s user entities: 
X-External-User-Id: user_12345
This is useful when you want to associate traces with your own user IDs without exposing WhyOps internal user IDs.

​
The ingestion pipeline

​
What happens on ingest

WhyOps validates the payload, merges auth context, enqueues the event when Redis is available, processes it sequentially per trace, resolves sampling plus missing step or span identifiers, and persists the final event to trace_events. If queueing is unavailable, the controller falls back to direct synchronous processing.

​
Ingesting Events

Use the /events/ingest endpoint to send one or more events.

​
POST /api/events/ingest

Accepts a single event object or an array of event objects. 
curl -X POST https://a.whyops.com/api/events/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "traceId": "123e4567-e89b-12d3-a456-426614174000",
    "spanId": "tool-call-1",
    "eventType": "tool_call_request",
    "agentName": "my-customer-support-agent",
    "timestamp": "2024-03-20T12:00:00Z",
    "content": {
      "toolCalls": [
        {
          "name": "search_database",
          "arguments": { "query": "latest orders" }
        }
      ]
    },
    "metadata": {
      "tool": "search_database"
    }
  }'

TypeScript Runtime Guide

Use the @whyops/sdk trace builder instead of hand-rolling the event payloads in Node.js or Bun services.

Python Runtime Guide

Use the whyops sync and async trace helpers instead of posting raw REST payloads in Python services.

​
Response behavior

  • 202 Accepted when the event was queued successfully
  • 201 Created when it falls back to direct processing
  • 400 for validation or missing auth context
  • 409 when a trace is already bound to a different agent version
Typical queued response: 
{
  "success": true,
  "accepted": true,
  "queuedCount": 1
}

​
Other useful endpoints

  • POST /api/events processes events directly instead of queue-first and accepts the same payload shape.
  • POST /api/events/tool-result is a convenience endpoint that automatically sets eventType: "tool_call_response".
  • GET /api/events/help returns the machine-readable help payload for supported event types.
  • GET /api/events?traceId=...&include=content,metadata and GET /api/events/:id?include=content,metadata let you inspect stored events while debugging.

​
Event schema summary

Every event you send must conform to this schema:
FieldTypeRequiredDescription
eventTypestringYesSee below for allowed types.
traceIdstringYes1-128 chars. Groups events into a single agent run.
agentNamestringYes1-255 chars. Identifies the specific agent.
spanIdstringNoLinks related requests and responses (e.g. tool calls).
stepIdintegerNoUsed for ordering events sequentially (>= 1).
parentStepIdintegerNoUsed to build nested tree structures (>= 1).
timestampstringNoISO 8601 string. Defaults to the time received.
contentanyNoThe actual payload (e.g., messages, tool outputs).
metadataobjectNoAdditional context (e.g., latency, tokens, model used).
idempotencyKeystringNoPrevents duplicate event ingestion.
externalUserIdstringNoYour application user ID to link traces to end-user entities.

​
How step and span resolution works

If you do not send stepId, WhyOps auto-increments from the last event in that trace. If you do not send parentStepId, WhyOps uses the previous step as parent. If you do not send spanId, WhyOps generates one for you. Recommendation:
  • explicitly set spanId for request/response pairs
  • optionally let WhyOps generate stepId unless you already have a stable internal step model

​
Allowed event types

To ensure accurate static analysis and graph rendering, you must use one of the predefined event types.

​
LLM Interactions

  • user_message: user input to the model or the full message history.
  • llm_response: model response content and optional tool calls. Requires metadata.model and metadata.provider.
  • embedding_request: input payload sent to an embedding provider.
  • embedding_response: output summary from an embedding provider. Requires metadata.model and metadata.provider.
  • llm_thinking: internal reasoning blocks such as Anthropic thinking.

​
Tool Execution

  • tool_call: legacy combined tool call event; backend splits it into tool_call_request + tool_call_response automatically.
  • tool_call_request: a request to execute a tool. Requires metadata.tool.
  • tool_call_response: the output returned from a tool execution. Requires metadata.tool.
  • tool_result: tool results returned back to the model by your framework.

​
Errors

  • error: upstream API failures, tool crashes, framework exceptions, or app-side failures.

​
Detailed payload reference

The full payload catalog, runtime patterns, idempotency rules, and tool pipeline examples are documented in Manual Events Reference.