Skip to content

API_USAGE_BETA.md

Latest commit

 

History

History
164 lines (134 loc) · 8.67 KB

API_USAGE_BETA.md

File metadata and controls

164 lines (134 loc) · 8.67 KB
Raw

API billing snapshots

Electron 0.3.0-beta.6, build 75 includes separate OpenAI API and Anthropic API billing cards. OpenRouter keeps its existing account balance, key limits and aggregate activity integration.

What the cards report

OpenAI API and Anthropic API show provider-reported USD cost buckets for the current UTC month through the request time. They are separate from Codex and Claude subscriptions and from locally estimated token costs. Empty reports remain unavailable; a provider-reported zero is displayed as zero. These cards do not invent token counts, budgets or quota percentages.

The card shows the report period and exact snapshot time. A snapshot becomes stale after 24 hours or a UTC-month change. A prior month's snapshot retains its own period. Refresh rereads the file; it does not fetch billing or make an old snapshot fresh. Anthropic's cost report excludes Priority Tier costs. Neither provider's report replaces its dashboard or invoice.

OpenAI remaining balance

The OpenAI API card also shows the dollars left. OpenAI documents no balance endpoint, so the fetch first tries the unofficial credit_grants report with the same key. A result is labelled OpenAI credit grants (unofficial) and shows the amount left, used and granted. This report may reject Admin keys or change without notice; its failure never stops the spend fetch. A report with zero credit granted counts as no balance, so the fallback below can run.

If it fails, enter Prepaid credit (USD) and Added on (UTC date) under OpenAI API in Settings, save, then fetch billing again. The card shows ~$X left, calculated as the prepaid amount minus Costs API spend since that date. Update both values after each top-up. The estimate does not see refunds, expiring grants or invoice adjustments. When spend exceeds the prepaid amount, the card asks you to update it. Spend on the whole top-up day counts, including any before the top-up. A future date is ignored, and the estimate is skipped if the date is more than about 2.5 years back. Clear turns the fallback off for later fetches; an estimate already on the card stays until the next fetch. The Terminal helper tries only the credit grants report.

Set up in Settings

  1. Open Settings → API connections.
  2. If you saved an Admin key in the previous MeterUsage, click Use saved key for that provider. Approve macOS Keychain access if asked. This fetches billing without entering the key again.
  3. Otherwise, create an organization Admin key in OpenAI Platform → Organization settings → Admin keys, or Anthropic Console → Settings → Admin keys.
  4. Paste the key into the matching provider's masked field and click Fetch billing.

MeterUsage clears the field on submit and updates the billing snapshot after a successful request. Pasted keys are not saved. Use Use saved key again to refresh with an existing Keychain key; otherwise, enter a one-time key. Leaving the API page clears unsubmitted input. A normal project key or ChatGPT or Claude subscription sign-in cannot read organization billing.

The key passes through the trusted Settings bridge to a one-time main-process request to that provider. A pasted key never enters preferences, Keychain, diagnostic reports or billing snapshots. There is no background billing fetch. Demo and isolated profiles cannot fetch billing. Keep keys out of chat and documentation.

Authentication failure means the key is invalid or lacks organization access. Data unavailable means no supported report could be fetched. Check the provider billing dashboard; a failed fetch preserves the previous snapshot. Refresh rereads snapshots without contacting the billing API.

Saved-key access reads only the previous app's fixed com.meterusage.api-keys Keychain service and openAI or anthropic account. The key stays in the main process and native helper; it is never returned to the UI or copied elsewhere. The original entry is not changed or deleted. Missing and denied entries show a fixed error, with no environment or other-account fallback. Keychain is read only after the explicit action, never at startup or during polling.

Advanced: use the helper

The bundled environment-only helper remains available. Open Terminal on your Mac, paste the matching command below, then paste the Admin key at the hidden prompt and press Return. The commands use macOS zsh. The entered key is not a command, so it does not enter shell history. The subshell supplies only the selected environment variable to the helper and exits afterward. The parent shell and MeterUsage do not save the entered key. Never put a key in command text, a profile, a repository or chat.

OpenAI API:

(
  IFS= read -rs 'OPENAI_ADMIN_KEY?Paste OpenAI Admin key (hidden): ' || exit 1
  print
  export OPENAI_ADMIN_KEY
  ELECTRON_RUN_AS_NODE=1 /Applications/MeterUsage.app/Contents/MacOS/meterusage \
    /Applications/MeterUsage.app/Contents/Resources/api-usage-helper.cjs openai
)

Anthropic API:

(
  IFS= read -rs 'ANTHROPIC_ADMIN_KEY?Paste Anthropic Admin key (hidden): ' || exit 1
  print
  export ANTHROPIC_ADMIN_KEY
  ELECTRON_RUN_AS_NODE=1 /Applications/MeterUsage.app/Contents/MacOS/meterusage \
    /Applications/MeterUsage.app/Contents/Resources/api-usage-helper.cjs anthropic
)

After API billing snapshot updated, click Refresh in MeterUsage. An API billing authentication failed result means the supplied key lacks access or is invalid. API billing data unavailable means the helper could not obtain a supported report; check the organization billing dashboard. A failed fetch preserves the last snapshot. A missing helper environment produces the fixed API billing admin key missing from helper environment result.

These commands contain no key. An existing trusted secret manager can instead supply the selected environment variable directly to the one-run helper. The helper removes that variable from its own environment before fetching. Source contributors can use node dist/api-helper/api-usage-helper.cjs openai or anthropic after building, with the same environment requirement.

The helper makes bounded HTTPS GET requests to the provider's documented cost report, follows pagination, drops identifiers and writes one owner-readable snapshot under ~/Library/Application Support/MeterUsage/api-usage/:

  • openai.json for OpenAI API
  • anthropic.json for Anthropic API

Snapshots and their final directory use owner-only permissions. The reader rejects unsafe paths, permissions, duplicate/malformed fields and unsupported currency. Successful writes replace the file atomically. A failed collection preserves the previous snapshot. The helper prints only a fixed success or error category, including authentication failure. It has no scheduler or background key storage. Rerun the matching helper command when you need a new report, then refresh MeterUsage to reread the snapshot. Refresh does not contact the billing API. Remove the provider's snapshot to stop displaying that billing card. OpenRouter account activity and key limits continue to use its existing integration.

Data and credential boundary

The Settings action receives a one-time key in memory; the advanced helper receives its key through the environment. Both use the same fixed-endpoint collector and write only normalized numeric snapshots. A snapshot contains schema/provider, capture and period timestamps, USD currency, and daily start/end/amount values. It excludes raw responses and organization, project, workspace, user and key identifiers. Keys, authorization headers and provider error bodies are never written to snapshots, diagnostics or the renderer.

Requests refuse redirects, share a 30-second deadline, bound each response to 1 MiB and stop after bounded or repeated pagination. OpenAI dollar amounts are used as reported. Anthropic decimal cents are converted to USD. Non-USD amounts stay unavailable; there is no currency conversion.

Official contracts and proof limits

Synthetic fixtures verify projection, units, pagination, privacy, freshness and failure behavior. OpenAI saved-key recovery through the installed signed helper succeeded. The live Settings button journey, Anthropic billing and complete invoice reconciliation remain unverified. No real Admin key is required for source tests.