Cost and usage

Qoder Agent SDK exposes both Credits and token usage data. They serve different purposes and are measured differently:

Credits are Qoder's resource usage unit. This guide focuses on querying Credits.
Tokens represent the amount of model input, output, and cached text. They cannot be converted directly to Credits.

For product rules, quota types, and deduction order, see Credits.

View Credits usage

Depending on the scope you need, the SDK provides Credits usage for account quotas, individual model requests, and the current session total:

What you want to view	TypeScript	Python	Scope
Account quota and current session usage	`q.getUsageInfo()`	`client.get_usage_info()`	A real-time snapshot of the account and current CLI session
Individual model request usage	`message.message.usage`	`message.usage`	One completed model request
Current session total	`result.total_credits`, `result.modelUsage`	`result.total_credits`, `result.model_usage`	Cumulative values from the start of the current CLI session through the Result message

If you only need the current quota in application code and do not want to wait for an Agent task to finish, use getUsageInfo() / get_usage_info(). To record each model request or settle usage at the end of a session, read the message stream. In TypeScript, the two session statistics use different naming conventions: getUsageInfo().session uses total_credits and model_usage, while Result messages use total_credits and modelUsage. Python uses snake_case in both places.

Query Credits usage directly

getUsageInfo() / get_usage_info() returns account quota information and, when available, cumulative Credits for the current CLI session in session.

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

let releaseInput: (() => void) | undefined;

// Keep the CLI session alive without starting an Agent turn.
async function* noPrompt() {
  await new Promise<void>((resolve) => {
    releaseInput = resolve;
  });
}

const q = query({
  prompt: noPrompt(),
  options: {
    auth: accessTokenFromEnv(),
  },
});

try {
  await q.initializationResult();

  const usage = await q.getUsageInfo();
  if (usage === null) {
    console.log('Usage is unavailable.');
  } else {
    console.log('Plan:', usage.userType);
    console.log('Overall usage:', usage.totalUsagePercentage);
    console.log('Plan Credits remaining:', usage.userQuota?.remaining);

    if (usage.session) {
      console.log('Session Credits:', usage.session.total_credits);
      for (const [model, modelUsage] of Object.entries(
        usage.session.model_usage,
      )) {
        console.log(model, modelUsage.credits);
      }
    }
  }
} finally {
  releaseInput?.();
  await q.close();
}

Common response fields:

Field	Description
`userQuota`	Quota included in the current plan, with `total`, `used`, `remaining`, `percentage`, and `unit`
`addOnQuota`	Purchased add-on quota; may be absent when the account has no add-on quota. When present, `detailUrl` points to the usage details page
`orgResourcePackage`	Shared organization resource package. Uses `cap` for the total quota and provides `used`, `remaining`, `percentage`, `available`, and `unit`
`totalUsagePercentage`	Overall usage percentage across all quotas available to the account
`isQuotaExceeded`	Whether the account has exhausted its available quota
`session.total_credits`	Cumulative Credits for the current CLI session
`session.model_usage`	Cumulative Credits for the current session, grouped by model

Account quota data and session are independent. If the account quota service is temporarily unavailable, the SDK may still return an object containing only session. Do not use the presence of userId or userQuota to determine whether session usage is available. A null / None result means that neither account quota nor session Credits were available for this request. In addition to an unauthenticated account or an older unsupported CLI version, a failed control request or a temporarily unavailable service can also cause this result. For the complete API definitions, see SDK References.

Read Credits from session messages

The message stream provides both per-request and cumulative session statistics. The following example prints:

Credits for each model request from Assistant messages;
cumulative Credits for the current session from the Result message;
cumulative Credits grouped by model from the Result message.

One Agent task can trigger multiple model requests, so the stream may contain multiple Assistant messages with request-level Credits. If you only need the current session total, use total_credits from the Result message and do not add request-level credits to it.

import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Summarize this repository.',
  options: {
    auth: accessTokenFromEnv(),
  },
})) {
  if (message.type === 'assistant') {
    const usage = message.message.usage;

    if (typeof usage?.credits === 'number') {
      console.log('Request Credits:', usage.credits);
      console.log('Original Credits:', usage.original_credits);
      console.log('Billable:', usage.billable);
    }
  }

  if (message.type === 'result') {
    if (typeof message.total_credits === 'number') {
      console.log('Session Credits:', message.total_credits);
    }

    for (const [model, modelUsage] of Object.entries(message.modelUsage)) {
      if (typeof modelUsage.credits === 'number') {
        console.log(model, modelUsage.credits);
      }
    }
  }
}

Field meanings

Field	Scope	Description
`credits`	Individual model request	Credits after promotions or discounts are applied
`original_credits`	Individual model request	Credits before promotions or discounts are applied; omitted when unavailable
`billable`	Individual model request	Whether the request counts toward the user's Credits usage
`total_credits`	Current session total	Credits accumulated since the current CLI session started
TypeScript `modelUsage[model].credits`	Current session total	Credits accumulated by a specific model in the current session
Python `model_usage[model]["credits"]`	Current session total	Credits accumulated by a specific model in the current session

Note: Do not read Credits from the Result message's usage field. result.usage contains token and related usage data, but not the request-level credits, original_credits, or billable fields. Read request-level Credits from Assistant messages, and cumulative session Credits from total_credits or the per-model statistics.

Compatibility

Credits fields are optional for compatibility with older CLI versions. Check that a field exists before reading it, and do not treat a missing value as 0.
total_credits is a cumulative session value. Do not add the value from multiple Result messages, or usage may be counted more than once.
Request-level credits and cumulative session Credits in a Result message are different scopes for the same consumption. Do not add them together.
Token fields such as input_tokens and output_tokens have no fixed conversion to Credits.
To display remaining account quota, use the quota buckets returned by getUsageInfo() / get_usage_info() instead of estimating it by adding session messages.

Next steps

Credits — Credits types, deduction order, and ways to view usage
SDK References — Complete message and control API definitions

​View Credits usage

​Query Credits usage directly

​Read Credits from session messages

​Field meanings