preview_access_code_cost

Preview the cost of generating access codes before queuing the batch. Returns free_remaining, chargeable_quantity, and cost.

Purpose

Preview the cost of generating access codes before queuing the batch. Returns free_remaining, chargeable_quantity, and the resulting cost in the creator-tier currency so the agent can surface the charge to a human. Always call this first when quantity might exceed the creator tier free allotment — the generation tool refuses to run with chargeable codes unless the caller acknowledges overage.

Required ability

project-access-code:create

Input schema

{
  "type": "object",
  "required": ["plan_id", "quantity"],
  "properties": {
    "plan_id": {
      "type": "string",
      "description": "UUID of the plan the batch would be attached to."
    },
    "quantity": {
      "type": "integer",
      "minimum": 1,
      "maximum": 10000,
      "description": "How many access codes the agent is considering generating (1-10000)."
    }
  }
}

Output shape

{
  "data": {
    "plan_id": "pln_01HX...",
    "quantity": 50,
    "preview": {
      "free_remaining": 3,
      "chargeable_quantity": 47,
      "cost": "1.41"
    },
    "will_bill_overage": true
  }
}

Example prompts

"Preview the cost of generating 200 access codes for plan pln_01HX...."

"Before I hand out codes, tell me whether this would trigger an overage charge."

Failure modes

RESOURCE_NOT_FOUND — unknown plan_id, or the plan belongs to a team outside the token's scope.
VALIDATION_FAILED — quantity is outside the 1..10,000 range.
AUTHENTICATION_REQUIRED — no authenticated user on the request.
TOKEN_MISSING_ABILITY — token lacks project-access-code:create.