Event schema

Authoritative field reference for every event type accepted by /ingest/batch and /ingest/event.

Batch envelope

Send up to 1,000 events per request. The body must be a JSON object with an events array. Each element is an object with a type string and a data object:

json

POST https://api.obsivara.com/ingest/batch
Authorization: Bearer obs_live_YOUR_KEY
Content-Type: application/json

{
  "events": [
    {
      "type": "run_start",
      "data": {
        "name": "Support reply",
        "assetId": "support-agent",
        "input": "where is my order?"
      }
    },
    {
      "type": "llm_call",
      "data": {
        "runId": "550e8400-e29b-41d4-a716-446655440000",
        "provider": "openai",
        "model": "gpt-4o",
        "promptTokens": 312,
        "completionTokens": 87,
        "totalTokens": 399,
        "costUsd": 0.0048,
        "latencyMs": 1240
      }
    },
    {
      "type": "run_end",
      "data": {
        "runId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "success",
        "durationMs": 3500
      }
    }
  ]
}

Success returns HTTP 202:

json

HTTP/1.1 202 Accepted
{
  "accepted": 3,
  "rejected": 0,
  "errors": []
}

If some events are invalid, the batch still returns 202 but rejected will be greater than zero and errors will list the per-index failures:

json

HTTP/1.1 202 Accepted
{
  "accepted": 2,
  "rejected": 1,
  "errors": [
    { "index": 1, "error": "runId must be a valid UUID" }
  ]
}

The maximum batch size is 1,000 events. Batches larger than this are rejected with HTTP 413. Split large payloads into multiple requests.

run_start

Marks the beginning of a run. Generates a runId UUID if one is not provided.

Field	Type	Required?	Notes
`name`	string	Required	Human-readable run name
`assetId`	string	Required	The asset being monitored
`runId`	UUID	Optional	Auto-generated if omitted; use this ID in subsequent events
`input`	any	Optional	The input data for this run
`userId`	string	Optional	End-user identifier
`traceId`	string	Optional	Distributed trace ID for correlation
`metadata`	object	Optional	Arbitrary key-value metadata
`startedAt`	ISO 8601	Optional	Defaults to server receive time

run_end

Marks the end of a run. Must reference an existing runId UUID.

Field	Type	Required?	Notes
`runId`	UUID	Required	Must be a valid UUID from a preceding `run_start`
`status`	string	Required	One of `success`, `error`, `timeout`
`durationMs`	number	Required	Total run duration in milliseconds
`totalTokens`	number	Optional	Aggregate token count for the run
`totalCost`	number	Optional	Aggregate cost in USD
`output`	any	Optional	The final output of the run
`errorMessage`	string	Optional	Error description if status is `error`

llm_call

Records a single LLM invocation within a run. All numeric fields are required.

Field	Type	Required?	Notes
`runId`	UUID	Required	Must be a valid UUID from a preceding `run_start`
`provider`	string	Required	Model provider (e.g. `openai`, `anthropic`)
`model`	string	Required	Model name (e.g. `gpt-4o`, `claude-3-5-sonnet`)
`promptTokens`	number	Required	Input token count
`completionTokens`	number	Required	Output token count
`totalTokens`	number	Required	Sum of prompt + completion tokens
`costUsd`	number	Required	Cost of this call in USD
`latencyMs`	number	Required	Time-to-first-token or total latency in ms
`prompt`	string	Optional	The full prompt text
`completion`	string	Optional	The full completion text
`temperature`	number	Optional	Sampling temperature used
`promptVersion`	string	Optional	Prompt version identifier
`metadata`	object	Optional	Arbitrary key-value metadata

tool_call

Records a tool or function call within a run.

Field	Type	Required?	Notes
`runId`	UUID	Required	Must be a valid UUID from a preceding `run_start`
`toolName`	string	Required	Name of the tool or function called
`status`	string	Required	One of `success`, `error`
`durationMs`	number	Required	Tool execution duration in milliseconds
`input`	any	Optional	Arguments passed to the tool
`output`	any	Optional	Return value from the tool
`errorMessage`	string	Optional	Error description if status is `error`

span

Records a generic span within a trace, compatible with OpenTelemetry concepts.

Field	Type	Required?	Notes
`traceId`	string	Required	Distributed trace identifier
`name`	string	Required	Span name
`durationMs`	number	Required	Span duration in milliseconds
`spanId`	string	Optional	Auto-generated if omitted
`runId`	UUID	Optional	Links this span to a run
`kind`	string	Optional	One of `llm`, `tool`, `retrieval`, `agent`, `function`. Default: `function`
`input`	any	Optional	Span input data
`output`	any	Optional	Span output data
`status`	string	Optional	One of `ok`, `error`. Default: `ok`
`metadata`	object	Optional	Arbitrary key-value metadata
`startedAt`	ISO 8601	Optional	Defaults to server receive time

error

Records an error event, optionally linked to a run or asset.

Field	Type	Required?	Notes
`message`	string	Required	Human-readable error description
`runId`	UUID	Optional	Links this error to a run
`assetId`	string	Optional	Links this error to an asset
`type`	string	Optional	Error type/class (e.g. `ValidationError`)
`severity`	string	Optional	Error severity level
`stackTrace`	string	Optional	Full stack trace
`metadata`	object	Optional	Arbitrary key-value metadata

Field naming convention

The /ingest/batch endpoint uses camelCase field names (e.g. assetId, promptTokens, durationMs). The generic webhook (/ingest/webhook/generic) uses snake_case (e.g. asset_id, prompt_tokens, duration_ms). Use the correct convention for the endpoint you are calling.