Agent Billing, Limits & Errors
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. 1 AI credit costs EUR 0.01, billed separately from messages, and included messages left over in a month also cover AI credits (see Invoice and included pool). Knowledge Base lookups are free. There is no extra fee per agent, skill or seat.
What an agent turn costs
Typical credits per use. The real cost depends on how much AI work a turn needs, so these are typical values, not fixed prices. The full list is in the AI credits price table.
| Usage | Fast | Advanced |
|---|---|---|
| A typical reply (also a draft in Assist mode) | about 1 to 2 | about 3 to 8 |
| A simple question (no web search or files) | under 1 | about 3 times Fast |
| Reading a customer's photo / PDF / voice message | about 0.5 / 0.8 / 0.3 | about 0.8 / 1.4 / 0.3 |
| Web search or live source read | 3 each | 3 each |
| One agent builder build (always Advanced) | about 12 to 18 |
Each turn is charged by the AI work it needs: what the agent reads (its instructions and skills, the conversation, knowledge base articles, files) and what it writes, at the agent's model_tier (standard = Fast, advanced = Advanced, about 3.3 times Fast). Credits are counted in fractions per turn. Only the monthly total on the invoice is rounded.
Agent specifics
- Web search, +3 credits: a web search that returns results (the
web_searchtool, or the automatic search ofweb_search_modekb_fallback/always), including a result served from the web search cache. - Live source read, +3 credits: a live source read that returns entries (by the agent, automatic or enforced).
- Files: the agent opens a customer's image or PDF only when the conversation needs it; reading it is part of the reply's AI work.
- Agent builder builds always run on Advanced. A generated skill suggestion ("Suggest improvements", on Advanced) costs the AI credits of that work.
Free:
- Knowledge Base search itself. The articles the agent reads become part of the reply's AI work.
- Translations and language detection.
- Web searches and live source reads that return nothing, fail or hit a limit, and reading the same live page again in the same reply.
- Images and PDFs that are skipped (switch off, over a limit, too large, unsupported type) or could not be read.
- Failed or cancelled AI runs (a reply or build that fails, times out or is cancelled), and fallback and error messages sent because something failed on our side.
- Turns stopped by the plan check (
gated) or by the per-conversation credit limit. - Creating an agent from a build.
- Skill suggestion requests that create no suggestion (
no_feedback,no_change), policy-rule suggestions from corrections, and approving or dismissing a suggestion. - The test console, up to 500 test turns per UTC day per billing account on paid plans (beyond that a test turn is charged like a live turn). Its
creditsobject shows what a live turn would cost (would_bill). During a free trial that amount is taken from the trial AI credits (never invoiced).
The per-conversation credit limit (max_credits_per_conversation) sums the AI credits of the conversation's turns. In the turn log, credits_exact is what a turn costs, with decimals, and the limit sums these values. credits_billed is the same amount rounded to a whole number, for display only. On older turns that were charged a fixed price, credits_exact is null and credits_billed is the price that was charged. The invoice adds up the exact values and rounds only the monthly total. If the advanced model is unavailable and the standard model writes the reply, that reply is charged at the Fast level.
File summaries for your team
The summary an agent writes of each image or PDF it read is reused, free of charge, for your human team: it appears as ai_summary on the attachment in the conversation view, the mobile app and the Messages API, and as the attachment.summarized webhook event. For a customer image or PDF without a summary, a team member or API client can request one on demand (POST /api/v1/attachments/{attachment_id}/summary). On-demand summaries run on the workspace's Attachments in chat level in Settings > AI (default Fast) and are charged by the AI work of the summary, once per file. A summary that already exists, or one that could not be made, is free. Only inbound customer images and PDFs are eligible (PDFs: first 10 pages), and only while AI is enabled for the workspace. The summary text is untrusted customer-file content: render it as plain text.
Where to see it
GET /api/v1/billing/ai-usage returns the AI credits per feature group, with one item per agent in the agents group. GET /api/v1/billing/tenant-usage returns an ai_credits breakdown per workspace with the buckets bot_messages, tool_usage and other (other.by_charge.ai_credits holds the AI credits charged by usage, tool_usage.by_charge.web_search the web searches and live source reads). 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 |
| Images read per message | max_images_per_message, 1-3, default 3 |
| PDFs read per message | 2, first 10 pages, max 20 MB each |
| Images and PDFs read per conversation | max_attachments_per_conversation, 1-50, default 10 |
Test console attachment_ids | 5 per turn |
max_tool_calls | 1-6, default 4 |
turn_time_limits | 30 or 60 seconds (maximum 60) per channel group (default, live_chat, email); new agents start with default: 30. See Turn time limits. |
turn_timeout_ms | Legacy budget, used only while turn_time_limits.default is not set: 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 |
| Live source reads | 2 per reply, 20 per conversation, 2,000 per workspace per day |
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 |
choose_tag.tag_ids | 2-10; the agent picks 1-3 (max) |
| Paused goals per conversation | 3 |
Rate limits
| Endpoint | Limit | Response |
|---|---|---|
POST /automation/agents/{agent_id}/test | 20 per minute, 200 per hour per workspace; during a free trial also 60 per hour, 200 per day per account | 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 |
POST /automation/agents/{agent_id}/skill-suggestions/generate | 10 per hour per workspace (requests that find no feedback do not count) | 429 {"detail": {"code": "rate_limit_exceeded", …, "retry_after": …}} |
All 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 | "Missing required permission(s): automation:…" | 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 | {"code": "invalid_turn_time_limit"} | A turn time limit value or key is not allowed |
422 | {"code": "email_settings.invalid"} or email_settings.invalid_skill | Invalid email settings, or the triage skill is not in this workspace |
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, and validation errors are a list. Match on the status code first, then on detail.code when present. See Error handling for all shapes.
Beta caveats
- Limits, defaults and the
engine_tracecontent may change.engine_traceis for troubleshooting only and is not a stable contract. - Live sources, the web search cache and the grounding check are Beta: limits, the cache lifetime and what the grounding check treats as a checkable detail may change.
modelvalues 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 theescalatedbranch.