Limits & provider keys · Pinecall Docs

Your org has limits in the sandbox and in production: minutes, messages, calls at once, and a monthly budget among them. Its calls run on Pinecall's vendor keys unless you bring your own. This page is what that means for you; how an operator sets limits on a self-hosted runtime is Limits and provider keys.

What are the limits?#

The sandbox and production each have their own set. A limit nobody set is no limit; a limit of zero turns a feature off.

limit	counts	refused when it is reached
`minutes`	minutes of calls this month	a new call; a call let in ends when the minutes left run out
`messages`	written turns this month	a new conversation, or the next written turn
`llm_tokens`	model tokens this month	a new call, or the next written turn
`concurrent_calls`	calls open right now	a new call
`agents`	agents the org runs	a new agent
`memory_facts`	facts the agents remember about contacts	a new fact
`knowledge_chunks`	pieces of documents in knowledge bases	a push that would pass it, refused whole
`numbers`	numbers bought through Pinecall (imported ones do not count)	buying another
`seats`	people invited or active	another invitation
`hosted_apps`	projects Pinecall runs for you with `pinecall deploy`	a new app's first release
`budget_usd`	dollars spent this month, sandbox and production together	a new call

Monthly counts start again on the first of each month, UTC. A call that is already running is never cut for the budget.

How you see them#

The console's Usage screen shows what the org used, by day, by agent and call by call. Where minutes are limited, Usage and Overview show Minutes used · n of N. Any key of the org can read each limit beside what was used, in the sandbox or production as it asks, at GET /v1/limits.

A refusal names the limit, what was used and the limit itself:

429 the org has used 30 of its 30 minutes in the sandbox

The same numbers land in the agent's log as credits.exhausted.

Evals and simulations#

Two things run on Pinecall's keys and spend none of the limits above: the judges that read every finished call, and the simulated caller of a persona. Your org pays for them by the unit instead, each with a limit of its own a month — evals and simulations, the free trial's 500 and 10 in the sandbox, a paid plan's metered past what it includes — and Usage shows both:

unit	one is	never counted
eval	one judge that answered one call: `held`, `broken` or a classification	`na`, `deferred`, `skipped`, and every eval of a judge model on your own key
simulation	one call a simulated caller played

Past evals, a call still seals: the judges left are skipped, saying the month's evals are used up, and credits.exhausted lands on the agent's log once. Past simulations, a simulation is refused before it opens, and a run that reaches it stops where it is. A simulated call never counts minutes, and neither does a call an eval run opened. What the harness asks a model for beside a score — a judge tried, callers generated, a group diagnosed — is counted as evals too (evals.spent on the agent's log).

Name a judge model on your org's own key — pinecall judging --model, or an agent's @judge — and its evals are never billed nor counted: the model's bill is yours.

Whose vendor keys a call runs on#

A call uses three vendors: speech-to-text, a model, and a voice. For each one, Pinecall uses:

Your own keyWhen the org brought a key for that vendor. It runs every model of that vendor. Pinecall's keyWhen you brought none, and only for the vendors and models Pinecall lends your org there.

What Pinecall lends#

pinecall providers lists every vendor Pinecall runs, and whether each would run a call for your org now:

Terminal

$ pinecall providers --does tts

`standing`	means
`ready`	runs a call: on your own key, or on a key Pinecall lends you
`no key`	installed, but nothing would pay for it: bring your own key
`no plugin`	this vendor is not installed here

A call that asks for a vendor with no key behind it is refused before it opens.

Bringing your own key#

Terminal

$ pinecall providers add deepgram

The key is read from stdin, never from a flag, and never printed back. It is sealed when it is stored. From the next call on, every call of the org runs that vendor on your key, in the sandbox and in production.

command	does
`pinecall providers add <vendor>`	keep the org's key for a vendor, or replace it
`pinecall providers list`	the vendors the org brought a key for, names only
`pinecall providers rm <vendor>`	forget it; that vendor goes back to what Pinecall lends

The console's Settings ▸ Providers does the same. Bringing keys needs the providers scope: a manager's or an admin's key (Orgs, people and roles).

Pinecall may lend only some models of a vendor. With your own key for that vendor, you can run any of its models, and give its plugin options of your own: on a key Pinecall lends, a plugin's class and options are refused, because an option can send the plugin to another server.

Next steps#

Voice & model providersEvery vendor an agent can run on, and which are priced. Agent settingsChoosing the voice, the model and the ears of an agent. Sandbox and productionWhy the sandbox and production have their own limits.