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

# Core concepts

> Understand runs, cost events, outcomes, and customer attribution.

## Run

A run is one AI workflow execution. Examples:

* `support_reply`
* `contract_summary`
* `generate_report`

Runs group cost events and outcomes under one business action.

Runs have a lifecycle:

* `running`: the run has started but has not reported a terminal state
* `completed`: the workflow finished successfully
* `failed`: the workflow failed or was cancelled

If you use `margovia.openai(client)`, `margovia.anthropic(client)`, `wrapOpenAI(..., { autoTrack: true })`, `wrapAnthropic(..., { autoTrack: true })`, `trackOpenAI(...)`, or `trackAnthropic(...)`, the SDK handles this lifecycle and records provider cost for you.

If you use `margovia.track(...)`, the SDK handles the run lifecycle, but cost is recorded only when the code inside uses wrapped provider clients or manually calls `run.trackCost(...)`.

If you use `startRun(...)` manually, always call `run.complete(...)` or `run.fail(...)`.

## Cost event

A cost event records the money spent inside a run. Usually this is one model provider call, tool call, or manually priced operation.

Cost events can include:

* Provider and model
* Input and output tokens
* Cached input tokens
* Cache creation tokens
* Reasoning tokens
* Manual `costUsd`
* Latency and status

Runs and cost events are separate. A run can exist without cost events, but then Margovia cannot calculate provider spend for that run. For normal OpenAI and Anthropic calls, use `margovia.openai(client)` or `margovia.anthropic(client)` so cost events are recorded automatically.

## Outcome

An outcome records what the run produced or what business value it created.

Examples:

* `reply_generated`
* `summary_created`
* `lead_qualified`
* `report_exported`

## Customer attribution

Margovia works best when every AI workflow includes customer and plan context:

```ts theme={null}
{
  customerId: "workspace_123",
  customerName: "Northstar Agency",
  customerPlan: { name: "pro", monthlyUsd: 99 }
}
```

This lets Margovia calculate cost and margin by customer, plan, and workflow.

`customerId` should be your stable join key back to your app or billing system. Margovia does not rewrite this value.

Good IDs are namespaced and stable:

```ts theme={null}
customerId: `workspace_${workspace.id}`
customerId: `org_${organization.id}`
customerId: `stripe_${stripeCustomer.id}`
```

Avoid unqualified numeric IDs like `"1"` when possible. If your internal ID is numeric, prefix it before sending, such as `workspace_1`.