Agent Billing, Limits & Errors

Beta

Conversational Agents are in Beta and available on Professional, Scale and Enterprise. Limits on this page may change during the Beta.

AI credits

Agents are billed in AI credits, drawn from your plan's included message pool like every other message. There is no extra fee per agent, skill or seat.

Usage	AI credits	Charge key
Each message the agent sends (model_tier: standard, "Fast"; also greetings and the AI note)	1 per message, on top of the normal message charge	bot_message
Each reply written by model_tier: advanced ("Deeper thinking")	2 per message, on top of the normal message charge	bot_message
search_knowledge that finds something	+1	kb_lookup
web_search that returns results	+3	web_search
Reading an image the contact sent (image understanding on)	+2	image_analysis
A successful agent builder build	100	agent_builder

Free:

• The skill classifier (router), load_skill, set_state, handoff, complete_task and the goal tools.
• Knowledge searches that find nothing or fail.
• Fallback and error messages sent because something failed on our side.
• Turns stopped by the plan check (gated).
• Failed agent builder builds, and creating an agent from a build.
• The test console. Its credits object shows what a live turn would cost (would_bill) with billed: false.

Tool credits are the same on both tiers. If the advanced model is unavailable and the standard model writes the reply, that reply bills 1 credit per message. Each turn's billed credits are in credits_billed in the turn log.

Where to see it

GET /api/v1/billing/tenant-usage returns an ai_credits breakdown per workspace with the buckets bot_messages, tool_usage and other, and the charge keys above in by_charge. See AI credits — Usage breakdown API.

Limits

Agents and skills

Limit	Value
Skills linked to one agent	50
Knowledge sources per agent	20
allowed_domains per web search source	50
Agent instructions, skill body	20,000 characters
Skill description	1,000 characters
Skills per import	100
handoff_config.keywords	50
handoff_config.handoff_tag_ids	20
handoff_config size	8 KB
tools_config size	1 KB
max_tool_calls	1-6, default 4
turn_timeout_ms	2,000-15,000, default 8,000 (advanced agents: always 15,000)

Per turn

Limit	Value
Skills preloaded by the classifier	2
Loaded skill text	60,000 characters
Conversation history read	Last 20 turns
Knowledge excerpts per search	5 (6,000 characters) from up to 8 sources
Web results per search	5
Web searches per conversation	3 by default; a daily workspace limit also applies
Conversation state (set_state)	30 keys, 500 characters per value, 8 KB in total

Skill goals

Limit	Value
Outputs per goal	20
Options per select output	100
max_attempts per output	1-5, default 3
assign.add_tag_ids	10
Paused goals per conversation	3

Rate limits

Endpoint	Limit	Response
POST /automation/agents/{agent_id}/test	20 per minute, 200 per hour per workspace	429 {"detail": {"error": "rate_limit_exceeded", "message": "…", "retry_after": …}}
POST /automation/agent-builder/generate	5 per hour, 20 per day per workspace; 1 build at a time	429 {"detail": {"code": "rate_limit_exceeded", …, "retry_after": …}}, 409 build_in_progress

Both 429 responses set the Retry-After header.

Test console requests

Field	Limit
message	4,000 characters
history	50 items
state	8 KB
task	16 KB; goal_prompt 4,000 characters

Common errors

Status	Body	When
401		Missing or invalid API token
403	{"detail": {"code": "feature_disabled", "feature": "ai_agents"}}	The plan does not include Conversational Agents (or ai_features)
403	"Insufficient scopes"	The token lacks the required automation:* scope
404	"Agent not found", "Skill not found", …	Unknown id, or an id from another workspace
409	{"code": "agent_in_use", "flows": […]}	Deleting an agent that a Flow uses
409	{"code": "skill_slug_exists"}	Creating a skill with a slug that is taken
422	{"code": "invalid_goal", "errors": […]}	Invalid skill goal
422	{"code": "invalid_handoff_tags", "tag_ids": […]}	Unknown hand-off tags
422	Validation error list	Field lengths, enums, JSON size limits, unknown fields
429	rate_limit_exceeded	See Rate limits

Error bodies are not fully uniform: some detail values are plain strings, others objects with a code. Match on the status code first, then on detail.code when present.

Beta caveats

• Limits, defaults and the engine_trace content may change. engine_trace is for troubleshooting only and is not a stable contract.
• model values in responses are informational; the models behind an agent can change without notice.
• Agent replies are AI generated. Test every skill in the test console before activating an agent, and keep escalation on so contacts can reach a human.
• If the plan stops including Conversational Agents, live agents stop answering (gated) and hand over if escalation is on. Flows take the escalated branch.