Ingest events

​

What ingest is for

npx @xerg/cli@latest ingest --file payload.json

​

The event payload format

{
  "version": 4,
  "source": { "name": "my-orchestrator", "environment": "staging" },
  "events": [
    {
      "id": "evt-1",
      "type": "model-call",
      "timestamp": "2026-07-01T10:00:01Z",
      "runId": "run-1",
      "workflow": "lead-enrichment",
      "provider": "openai",
      "model": "gpt-4o",
      "inputTokens": 4000,
      "outputTokens": 600,
      "costUsd": 0.012
    },
    {
      "id": "evt-2",
      "type": "tool-execution",
      "timestamp": "2026-07-01T10:00:02Z",
      "runId": "run-1",
      "modelCallId": "evt-1",
      "toolCallId": "tool-native-1",
      "tool": "crm-lookup"
    }
  ]
}

• id must be a stable, unique string per event. Xerg uses it for deterministic deduplication, so re-exporting the same history does not double-count.
• runId groups events into runs (a trace, session, or task execution).
• Four event types are accepted: model-call, agent-invocation, tool-execution, and delegation. Orchestration events are first-class — they are preserved in run structure (agent lists, tool attribution, delegation counts) and never filtered.
• Version 4 is current and adds the evidence needed for the latest detector and comparison contracts. Version 3 added stable request/cost-component IDs and content-free input, result, state, and cache-entry fingerprints. Version 2 added modelCallId and toolCallId; modelCallId must reference a model-call event in the same payload and runId. Versions 1 through 4 are accepted, but older payloads cannot gain evidence they did not contain.
• The public machine-readable contract is Xerg Event Payload v4 JSON Schema. Generate a minimal valid example with npx @xerg/cli@latest ingest --print-example.
• On model-call events, pass costUsd when your platform reports billed cost (it becomes observed spend). Without it, Xerg estimates from local model pricing; models it cannot price stay visible as unpriced rather than being silently zeroed.
• Numeric fields are validated strictly: inputTokens, outputTokens, retries, attempt, and iteration must be nonnegative integers; costUsd and latencyMs must be nonnegative finite numbers. Negative or fractional token/count values reject the payload.
• An optional outcome: { "status": "success" | "failure" | "partial" | "unknown" } marker can be attached to any event. It is carried through to run tags for future cost-per-outcome analysis.

​

Options

npx @xerg/cli@latest ingest --file payload.json --since 7d
npx @xerg/cli@latest ingest --file payload.json --details
npx @xerg/cli@latest ingest --file payload.json --json
npx @xerg/cli@latest ingest --file payload.json --compare
npx @xerg/cli@latest ingest --file payload.json --push