Credits

How credit balance, checkout, and credit consumption work.

Credits are quota used by API, MCP, and CLI operations. They let Epismo meter usage without changing the pack and track data model.

One credit is priced at $0.01. Checkout requires a minimum total purchase of 500 credits across all allocations.

Balance

Credit balance is resolved in the current personal or workspace context. In the API, use workspaceId when checking a workspace balance. In the CLI, the selected workspace or EPISMO_TOKEN determines the context.

epismo credit balance

The API returns:

{
	"balance": 1200,
	"shortfall": 0
}

shortfall is non-zero when the current operation or plan needs more credits than the selected context has available.

Checkout

Checkout starts a purchase flow and returns a URL.

epismo credit checkout --allocations '[{"userId":"user-id","quantity":500}]'

API payload:

{
	"allocations": [{ "userId": "user-id", "quantity": 500 }]
}

In a workspace context, allocations are associated with that workspace. In personal space, they apply to the authenticated user context.

Each allocation needs a non-empty userId and a positive integer quantity. The total quantity across all allocations must be at least 500 credits.

What consumes credits

Credits are consumed primarily by API and MCP calls. CLI commands follow the same usage model.

Tier	Cost	Includes
`pack.create`	5 credits	Creating workflows or contexts
`pack.search`	5 credits	Searching workflows or contexts
`suggestion.create`	5 credits	Creating suggestions (max 20 per account per day)
`alias.upsert`	5 credits	Creating or repointing an alias
`track.search`	2 credits	Searching tasks or goals
`suggestion.search`	2 credits	Listing or searching suggestions
`alias.list`	2 credits	Listing aliases
`standard_call`	1 credit	Reads, writes, bulk apply, likes, alias delete, getting/updating/resolving suggestions
`llm_generation`	AI token usage	LLM-based features such as chat and review generation

Pack reads cost 1 credit whether you request the outline, selected blockIds / stepIds, or full=true. Prefer outline and selective reads to keep agent context small, not to reduce credit cost.

Write operations are charged as standard calls. Failed validation does not consume credits.

Account and workspace management does not consume credits: workspaces, projects, members, installed agents, authentication, and checking balance or buying credits are all free. Only pack, track, alias, and suggestion operations are metered.

Epismo checks your balance before a credit-gated operation runs, and only counts the credit once the operation succeeds, so a failed search or read is not charged. A credit-gated operation can return 402 Payment Required when the selected context does not have enough credits.

Operational guidance

Check balance before batch jobs that perform many searches or detail gets.
Prefer outline and selective pack reads to keep agent context small.
Use workspace-scoped tokens in CI so credits are consumed from the intended workspace.