UsageEvent

@forge/monorepo

---

@forge/monorepo / backend/src / UsageEvent

Type Alias: UsageEvent

UsageEvent = object

Defined in: backend/src/usage/index.ts:12

Properties

audioSeconds?

readonly optional audioSeconds?: number

Defined in: backend/src/usage/index.ts:53

---

cachedInputTokens

readonly cachedInputTokens: number

Defined in: backend/src/usage/index.ts:36

---

cacheWriteTokens?

readonly optional cacheWriteTokens?: number

Defined in: backend/src/usage/index.ts:44

Tokens written into a prompt cache — task #247.

Optional, and absent means "not reported" rather than "none": rows written before this existed and a turn whose provider reports no breakdown are different facts, and a zero would merge them. The same rule imageCount follows.

---

conversationId?

readonly optional conversationId?: ConversationId

Defined in: backend/src/usage/index.ts:29

---

costMinorUnits

readonly costMinorUnits: number

Defined in: backend/src/usage/index.ts:55

Integer minor units in the tenant's accounting currency.

---

currency

readonly currency: string

Defined in: backend/src/usage/index.ts:56

---

id

readonly id: string

Defined in: backend/src/usage/index.ts:13

---

imageCount?

readonly optional imageCount?: number

Defined in: backend/src/usage/index.ts:52

Non-text input this turn carried — #185 AC-4.

Absent means "not counted", not "none". A row written before the count existed and a genuinely text-only turn are different facts, and a zero would merge them.

---

inputTokens

readonly inputTokens: number

Defined in: backend/src/usage/index.ts:34

---

modelId

readonly modelId: string

Defined in: backend/src/usage/index.ts:33

---

occurredAt

readonly occurredAt: string

Defined in: backend/src/usage/index.ts:57

---

outputTokens

readonly outputTokens: number

Defined in: backend/src/usage/index.ts:35

---

principalId?

readonly optional principalId?: PrincipalId

Defined in: backend/src/usage/index.ts:28

Who consumed it — #175.

A usage record carried a tenant and no principal, so "what has this person spent" was unanswerable: the data was never recorded. Per-user metrics and per-user limits both start here.

Stamped by the recorder from the trusted context, never from the event payload — the same rule tenantId follows, and for the same reason: a caller that could name the principal on a usage event could bill someone else's budget.

Optional on the type, because rows written before this exist and a record with an unknown principal is a fact rather than a thing to invent. It is nullable in storage for that reason too.

---

reasoningTokens?

readonly optional reasoningTokens?: number

Defined in: backend/src/usage/index.ts:45

---

runId

readonly runId: RunId

Defined in: backend/src/usage/index.ts:30

---

stepId?

readonly optional stepId?: string

Defined in: backend/src/usage/index.ts:31

---

tenantId

readonly tenantId: string

Defined in: backend/src/usage/index.ts:14

---

toolCallId?

readonly optional toolCallId?: string

Defined in: backend/src/usage/index.ts:32