> ## Documentation Index
> Fetch the complete documentation index at: https://xerg.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingest events

> Audit AI usage from any framework by exporting a Xerg event payload JSON file and running xerg ingest.

## What ingest is for

If your agent framework is not one of the built-in sources (OpenClaw, Hermes, Claude Code, Cursor CSV), you can still audit it. Export your usage as a Xerg event payload — a small, versioned JSON format — and run:

```bash theme={null}
npx @xerg/cli@latest ingest --file payload.json
```

The full audit pipeline runs on the payload: spend rollups, waste findings, recommendations, local snapshots, `--compare`, and `--push` all work the same way they do for built-in sources.

## The event payload format

```json theme={null}
{
  "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"
    }
  ]
}
```

Rules:

* `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

```bash theme={null}
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
```

The same output, persistence, and push flags as [audit](/docs/audit) apply: `--json`, `--markdown`, `--db`, `--no-db`, `--compare`, `--push`, `--dry-run`, and `--verbose`.

Invalid payloads fail with per-event error messages (bad timestamps, unknown event types, duplicate IDs) instead of partial results.