Credits and capacity

CreditsCopy Anchor Link

A conversation spends credits for the time from when the AI persona starts it to when it ends, rounded up to a whole credit for each conversation. Your plan sets how much time a credit covers and how many credits you get each day. The persona starts it at the events route's started event. Getting ready spends nothing, and a conversation that never starts spends no credit.

The API's times are UTC. Some carry no offset, such as renews_at from get your usage (2026-11-10T00:00:00): read a time with no offset as UTC, since JavaScript's new Date() reads such a string as local time. A conversation's credits come from the UTC day it started, and a running conversation's credits so far already count against what is left. Today's credits don't carry over to tomorrow; credits we add to your account last until they're spent, and are used once today's are gone. Get your usage shows what is left.

Conversations at onceCopy Anchor Link

Your plan sets how many conversations your API keys may have active at once, including ones still starting. Get your usage shows the limit and how many are active, and a new conversation past it is refused with a 409 whose code is concurrency_limit.

From your server, list your active conversations to see which ones hold a place, oldest first. To free a place, end a conversation by its id, for example one whose page closed without ending it. Both calls take your API key and reach only your organization's conversations: another organization's conversation answers 404.

A conversation you end this way ends as it does when the person hangs up, though for now its page's session.closed may name the reason error rather than close_requested (reasons). One that hasn't started ends at once and spends nothing. A running one ends within a few seconds, once the persona leaves, and spends credits until then; its place is free once it has ended. One that already ended is left as it is.

Time limitCopy Anchor Link

A conversation runs for the service's maximum unless you ask for less, with max_session_seconds in POST /conversation. A longer value runs for the maximum. About 30 seconds before the end, the persona is told to wrap up. The events route's started event, and session.expires_at in session.started, say when it ends.

When capacity is shortCopy Anchor Link

Conversations run on shared capacity, and some of it can be taken back while a conversation is on it. A conversation you start never waits in a queue: it starts within a few seconds, or it is turned away.

• No capacity right now. When no runtime can take the conversation within a few seconds, POST /conversation answers 429 with code capacity_unavailable, retry_after_seconds and a Retry-After header. Nothing was started or spent, and the same session token can create the conversation again while it is under 60 seconds old.
• Too many starts at once. When too many conversations start at the same moment, POST /conversation can answer 503 with code busy. Try again after retry_after_seconds.
• Getting ready. Once a runtime is held for the conversation, it can take up to about half a minute to get ready: preparing on the events route.
• Taken back. When the machine a conversation runs on is taken back, the conversation ends early: session.closed with reason error, or the room's connection drops before it comes. Either way, the events route's ended follows.

When a start is turned away or a conversation ends early, let the person start again: a new conversation usually starts on other capacity. See Errors for each code.