Developer documentation

Limits, Voice and usage

Experience quotas, separate owner capacity, retriable refusals and current billing limits.

Experience quotas

CMS label	Configuration key	Default	Accepted range
Turns per visitor per day	turns_per_visitor_per_day	40	1 to 100,000
Turns per experience per day	turns_per_experience_per_day	2,000	1 to 10,000,000
Visitors per IP per hour	visitors_per_ip_per_hour	20	1 to 100,000
Browser tasks per visitor per day	agent_runs_per_visitor_per_day	3	1 to 100
Browser tasks per experience per day	agent_runs_per_experience_per_day	50	1 to 100,000

Chat and browser daily limits use UTC days. Visitor limits apply to the runtime’s viewer identity; experience limits apply across its viewers.

Visitors per IP per hour limits new viewer session creation. It is separate from daily turns and browser runs.

Reloading does not increase the experience or owner account budgets. Clearing guest storage can create a new viewer identity and lose continuity; it does not reset aggregate budgets.

Owner capacity and admission

The experience owner pays for accepted usage. Owner account capacity is additional to the experience limits and includes separate browser minute, day and concurrent limits.

Only one unfinished browser run is admitted per viewer. Duplicate/retried admission does not charge the same browser run twice.

A browser run can be charged before a browser opens. A revocation between charging and opening can leave a charged failed run; the current system has no automatic refund path.

Defaults and configuration ranges are not prices, included allowances or a commercial agreement. Agree usage and support terms with your operator.

Exhausted or unavailable limits

A daily chat quota returns HTTP 429 embed_usage_limit_exceeded with Retry-After until UTC midnight. Follow the response’s interval rather than looping or reloading.

If shared chat quota enforcement is unavailable, HTTP 503 embed_usage_unavailable refuses admission before owner billing or model work. Retry after Retry-After, up to 60 seconds.

There is no per-process fallback. An uncertain counter response can conservatively consume daily quota without billing; the service does not replay that command.

Separate owner capacity can also refuse with usage_limit_exceeded or usage_service_unavailable. Follow the current response and ask the operator to check the owner’s configured capacity.

Voice

Voice is off by default. With Voice disabled, typed chat requests no synthesis and offers no audio replay. Server speech admission also refuses before owner billing.

Enabled Voice requires a secure context, microphone delegation and a viewer gesture for capture. Missing delegation hides capture controls; text chat remains available.

Speech and transcription use separate accepted owner usage. The current text-only controlled trial recorded zero TTS units; it does not establish microphone acceptance or speech quality.