Skip to main content

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. 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.

UsageFastAdvanced
A typical reply (also a draft in Assist mode)about 1 to 2about 3 to 8
A simple question (no web search or files)under 1about 3 times Fast
Reading a customer's photo / PDF / voice messageabout 0.5 / 0.8 / 0.3about 0.8 / 1.4 / 0.3
Web search or live source read3 each3 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_search tool, or the automatic search of web_search_mode kb_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 credits object 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​

LimitValue
Skills linked to one agent50
Knowledge sources per agent20
allowed_domains per web search source50
Agent instructions, skill body20,000 characters
Skill description1,000 characters
Skills per import100
handoff_config.keywords50
handoff_config.handoff_tag_ids20
handoff_config size8 KB
tools_config size1 KB
Images read per messagemax_images_per_message, 1-3, default 3
PDFs read per message2, first 10 pages, max 20 MB each
Images and PDFs read per conversationmax_attachments_per_conversation, 1-50, default 10
Test console attachment_ids5 per turn
max_tool_calls1-6, default 4
turn_time_limits30 or 60 seconds (maximum 60) per channel group (default, live_chat, email); new agents start with default: 30. See Turn time limits.
turn_timeout_msLegacy 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​

LimitValue
Skills preloaded by the classifier2
Loaded skill text60,000 characters
Conversation history readLast 20 turns
Knowledge excerpts per search5 (6,000 characters) from up to 8 sources
Web results per search5
Web searches per conversation3 by default; a daily workspace limit also applies
Live source reads2 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​

LimitValue
Outputs per goal20
Options per select output100
max_attempts per output1-5, default 3
assign.add_tag_ids10
choose_tag.tag_ids2-10; the agent picks 1-3 (max)
Paused goals per conversation3

Rate limits​

EndpointLimitResponse
POST /automation/agents/{agent_id}/test20 per minute, 200 per hour per workspace; during a free trial also 60 per hour, 200 per day per account429 {"detail": {"error": "rate_limit_exceeded", "message": "…", "retry_after": …}}
POST /automation/agent-builder/generate5 per hour, 20 per day per workspace; 1 build at a time429 {"detail": {"code": "rate_limit_exceeded", …, "retry_after": …}}, 409 build_in_progress
POST /automation/agents/{agent_id}/skill-suggestions/generate10 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​

FieldLimit
message4,000 characters
history50 items
state8 KB
task16 KB; goal_prompt 4,000 characters

Common errors​

StatusBodyWhen
401Missing 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_skillInvalid email settings, or the triage skill is not in this workspace
422Validation error listField lengths, enums, JSON size limits, unknown fields
429rate_limit_exceededSee 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_trace content may change. engine_trace is 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.
  • 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.