Pricing and Billing

After this guide an agent can predict what each call costs, keep working when the trial credits run out, and handle the 402 that tells it to top up.

How pricing works

An agent account is backed by a TutorFlow organization, and everything it does is paid from that organization's credit balance. Each priced call charges a fixed number of credits. The account buys credits at 2 US cents per credit: prices and balances are in credits; dollars appear in top-up amounts, the catalog's *Usd fields, and the overdraft invoice.

There is one balance per account. Every live key of the account spends it, and so does anything a person does in the TutorFlow editor for the account's organization. Test keys spend nothing.

Reads, updates, and content you supply yourself cost nothing. You pay when TutorFlow generates, narrates, renders, builds, or grades.

Content API prices

These are the priced Content API calls. Paths are under /v1/content/classrooms/{classroomId}. USD is credits at 2 cents each.

Examples:

• A six-lesson course: 3 + 6 × 3 = 21 credits, $0.42.
• A ten-question test: 3 credits, $0.06.
• A game, brief and build: 1 + 40 = 41 credits, $0.82.
• A four-scene video, narrated and rendered: 4 × 1 + 5 = 9 credits, $0.18.

A run answers with estimatedCredits before it starts and reports creditsCharged as it goes. When each charge happens, and what a failure costs, is in Content API Pricing.

The pricing catalog

GET /v1/platform/pricing-catalog is public and needs no key. It is generated from the same credit amounts the backend charges, priced at 2 cents per credit, so it never drifts from billing. GET /v1/platform/.well-known/agent.json quotes its prices from the same source.

curl https://api.tutorflow.io/v1/platform/pricing-catalog

What it served on 2026-10-17:

Every entry also has a description naming the Content API call it prices. Creating a video from your scenes is free, so it has no entry.

How to read an entry:

• A category with unitCredits above 0 is per unit: it charges baseCredits + unitCredits × units. amountUsd is the price of one unit and baseUsd the flat part.
• A category with unitCredits of 0 is flat: it charges baseCredits, and amountUsd is that flat price.

One entry, as served:

{
  "category": "course",
  "tier": "default",
  "catalogKey": "course.default",
  "amountUsd": 0.06,
  "baseUsd": 0.06,
  "unitCredits": 3,
  "baseCredits": 3,
  "unit": "lesson",
  "description": "POST /courses/generate: the curriculum flat (baseUsd), then per generated lesson.",
  "currency": "USD",
  "source": "organization_credit_amount_v3",
  "stripeLookupKey": "platform-agent-credits-usd-metered",
  "stripeMeterEventName": "agent_credits",
  "isActive": true
}

Every entry matches a Content API price in the table above. The game entry is a brief and a build together (1 + 40 credits). Simulations have no entry; their prices are in the table above.

Trial credits

A new agent account starts with 50 credits ($1.00). They work at once, without email verification or a payment method. Use a test key to build without spending them.

Check the balance

curl https://api.tutorflow.io/v1/platform/agent/account \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"

GET /v1/platform/agent/billing/status returns the same balance fields plus hasPaymentMethod, cardBrand, cardLast4, and billingMode. The Content API also answers GET /v1/content/credits and lists every charge, with the key that made it, at GET /v1/content/credits/history.

Buy credits

Both ways to buy need a verified email on the account. Until then they answer 403 email_verification_required. Resend the link with POST /v1/platform/agent/verify-email/resend, and have the person who owns the email open it.

Stripe checkout

curl -X POST https://api.tutorflow.io/v1/platform/agent/billing/session \
  -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY"

{
  "url": "https://tutorflow.io/agent-platform/checkout?token=...",
  "sessionId": "..."
}

Send url to a person. The page is valid for one hour. They choose an amount from $5 to $5,000 and pay through Stripe; no card data passes through the agent. The payment buys credits at 2 cents each: $10 buys 500 credits. Paying through checkout also verifies the card, which turns on metered overdraft (below).

USDC over x402

Where x402 is enabled (x402.enabled in GET /v1/platform/.well-known/agent.json), an agent can pay in USDC on Base without a card:

1. Ask for a deposit address for an amount from $5 to $5,000:

   bash複製程式碼

   curl -X POST https://api.tutorflow.io/v1/platform/agent/billing/x402/deposit \
     -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{ "amountUsd": 10 }'

   JSON複製程式碼

   {
     "scheme": "exact",
     "network": "eip155:8453",
     "payTo": "0x...",
     "amountUsd": 10,
     "expiresInSeconds": 300,
     "paymentUrl": "POST /v1/platform/agent/billing/x402"
   }

2. Pay exactly amountUsd in USDC to payTo.

3. Send the x402 payment payload in the x-payment header:

   bash複製程式碼

   curl -X POST https://api.tutorflow.io/v1/platform/agent/billing/x402 \
     -H "Authorization: Bearer $TUTORFLOW_CONTENT_API_KEY" \
     -H "x-payment: <x402 payment payload>"

   JSON複製程式碼

   { "isCredited": true, "credits": 550, "creditBalance": 1100 }

A payment that has not settled yet answers 402 x402_payment_failed. Retry after a few seconds.

Buying through these agent channels is only for agent accounts. A human organization's workspace gets 403 agent_channel_only and buys credits in TutorFlow Billing.

Metered overdraft

A metered overdraft lets priced calls continue past a zero balance and bills the card afterwards. Once the account has a verified card, it is metered: when the balance runs out, priced calls keep working and draw on an overdraft up to overdraftLimit, 1,000 credits ($20) unless TutorFlow set another limit for you.

• Only the overdraft is billed. Credits you bought are never billed again.
• Overdraft use is reported hourly to one Stripe meter, priced at 2 cents per credit, and Stripe invoices the card.
• A paid invoice clears the overdraft.
• A failed invoice payment blocks further priced calls until it is resolved.
• If the card is removed, no new overdraft is allowed; the overdraft already used stays until it is invoiced.

Past overdraftLimit, priced calls answer 402 like an empty prepaid balance.

When credits run out: the 402

On the Content API, a priced call the balance cannot cover answers 402 content_payment_required before anything is charged. For an agent account's key, the error also says how to top up:

{
  "error": {
    "code": "content_payment_required",
    "message": "The organization does not have enough available AI Credits for this request",
    "billingSessionUrl": "POST /v1/platform/agent/billing/session",
    "x402": {
      "scheme": "exact",
      "network": "eip155:8453",
      "minAmountUsd": 5,
      "maxAmountUsd": 5000,
      "depositAddressUrl": "POST /v1/platform/agent/billing/x402/deposit",
      "paymentUrl": "POST /v1/platform/agent/billing/x402"
    },
    "emailVerification": {
      "isRequired": true,
      "resendUrl": "POST /v1/platform/agent/verify-email/resend"
    },
    "status": 402,
    "requestId": "..."
  }
}

What an agent should do:

1. If GET /v1/platform/agent/account shows isEmailVerified: false, call resendUrl and ask the person who owns the email to open the link.
2. Call billingSessionUrl and send the checkout link to a person, or pay with USDC through x402.
3. Retry the call with the same Idempotency-Key once credits covers it.

Two other 402 codes come from the Content API: content_payment_failed (a failed payment blocks priced calls) and content_key_budget_exceeded (the key reached its own monthly credit limit). See Content API Pricing.

The billing routes are account routes, limited per account (1,000 requests per minute by default). Over the limit they answer 429 platform_rate_limit_exceeded; wait Retry-After seconds. See Rate Limiting.

Enterprise

For high volume, an SLA, or invoiced billing, contact TutorFlow.