Ingest events

​

What ingest is for

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

​

The event payload format

{
  "version": 2,
  "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 2 adds optional modelCallId and toolCallId fields. modelCallId must reference a model-call event in the same payload and runId; Xerg uses it before chronological association. Version 1 remains accepted.
• 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 --json
npx @xerg/cli@latest ingest --file payload.json --compare
npx @xerg/cli@latest ingest --file payload.json --push