Skip to main content

​
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: 
{
  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: 
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.