Box AI Units

Box AI Units

Box AI usage is gated by AI Units — a per-call consumption budget that depends on your Box plan. This page captures plan allocations, plugin opt-in controls, and what happens when units run out.

Full reference at references/box-ai-units.md.

Per-plan allocation

Plan	AI Units / month	What's included
Free Developer	1,000	Ask, Extract, Text Gen; multi-doc Ask yes; Hubs Q&A no; AI Studio no
Business / Business Plus	Purchase as needed	Ask, Extract, Text Gen (per-unit cost); multi-doc Ask no; Hubs Q&A no
Enterprise	1,000 included	Ask, Extract, Text Gen; Hubs Q&A yes (Enterprise feature); multi-doc Ask no; AI Studio no
Enterprise Plus	2,000 included	Above + multi-doc Ask yes
Enterprise Advanced	20,000 included	Above + AI Studio yes

Per-call unit consumption rates are not publicly published. Box directs prospects to sales for rate cards. Plan by knowing your allocation, not by counting per-call.

Per-skill consumption

Skill	Operation	Units / call	Frequency
box-ai-recall	/2.0/ai/ask	1+ (scales with input file count + prompt)	Per query
box-ai-extract	/2.0/ai/extract_structured	1+ (scales with file size + field count)	Per binary processed
box-ai-agent invoke	/2.0/ai_agents	1+	Per agent query
box-companion (AI path)	Same as box-ai-extract	Per binary	When generating companions for AI-supported formats
All other skills	None	0	N/A

Opt-in controls

The plugin defaults all AI-consuming behavior to OFF. In _box-memory.json.settings:

settings:
  ai_recall_enabled: false       # set true to allow /box-ai-recall
  ai_extract_enabled: false      # set true for /box-companion AI path + /box-ai-extract
  ai_studio_agent_enabled: false # set true for /box-ai-agent
  ai_model: null                 # let Box pick (default GPT-5 mini); override with a specific model

Users explicitly opt in. The plugin never silently consumes AI Units.

Workspace-level cost bounds (v0.2+ planned)

Coming in a future version:

settings:
  ai_budget:
    monthly_unit_cap: 500        # plugin tracks; refuses calls above this
    per_session_cap: 50          # also enforce per-session limit
    warn_at_pct: 80              # log warning when 80% of cap reached

Not in v0.1.0. Current behavior: opt-in flags only, no cap enforcement.

When you exhaust units

Box returns HTTP 402 (Payment Required) or a quota error when the monthly allocation runs out.

Plugin behavior:

1. Surface the error: "Box AI Unit quota reached. Falling back to non-AI paths. Quota refreshes at the start of next billing period."
2. Set ai_recall_enabled, ai_extract_enabled, etc. → false for the session
3. Continue providing service via non-AI paths (index recall, sparse companions)
4. On next session, re-detect tier and AI Units availability via /box-tier-detect --refresh

Bounding cost in practice

• Default to off. Users explicitly opt in.
• Suggest box-recall first for any query that could plausibly be exact-matched.
• Cap input file sets at the 25-file Box limit (you can't accidentally query 200 files).
• Use --check for companion freshness before regenerating (no AI cost for the check).
• Watch for 402. Falling back fast is better than retrying and burning units.

Trade-off vs the on-prem variant

The on-prem variant consumes zero AI Units — it makes no Box API calls. Different trade-off:

Cloud (this plugin)	On-prem
Uses AI Units for AI-powered skills	Zero AI Units (no Box AI access at all)
Box AI Extract handles OCR automatically	Companion falls back to "couldn't parse" for non-text formats
Semantic Q&A via box-ai-recall	Local index match only (no semantic)
AI Studio agents (Enterprise Advanced)	Not available

Both are valid choices.

See also

• Box AI Integration — what each AI skill does
• box-ai-recall, box-ai-extract, box-ai-agent — the AI-consuming skills
• Box AI Features in Business Plans (Box Support)
• Expanded AI API Access (Box Support)