Cost
What the library reads and writes around each call, measured in documents, and how to keep a budget for your own operations.
Convex bills and limits functions by the documents they read and write. The library adds a fixed number of reads around each handler. It does not add a read for each row: a row rule reuses the role and the tenant rows that the call already loaded.
What one call costs
Measured with countDocuments in the tests of both packages. The numbers
count your tables and the library's own tables. The session check of the auth
component comes on top (see below).
| Call | Reads | Writes | What they are |
|---|---|---|---|
| A page of a list query, 3 rows | 6 | 0 | user, organization, membership, and the 3 rows. The row rules add nothing |
A mutation of one row under a tenant rule | 4 | 1 | user, the row (for its tenant), membership, and the patch's own read. The handler's get is free |
| A write in a nested tenant (a client of an agency) | 3 | 1 | user, organization, membership. The parent check reuses the role |
A tool call with a request_id | 3 | 3 | user, organization, membership; the rate-limit window, the row, the activity row |
| The same call again (a retry that replays) | 6 | 1 | the same checks, the rate-limit window, and the stored activity row |
A tool call that asks a person ('approve') | 4 | 2 | user, the row (for its tenant), membership, the row again for the request's fingerprint; the rate-limit window, the request |
approve of a request | 10 | 4 | approver, request, change check, agent's user, request again, row, membership, the patch's read; request (twice), row, activity |
The session check
A person's call first checks the Better Auth session: 2 more reads in the
auth component. In starters/mcp-oauth-agent, a page of three projects reads
8 documents and renaming one project reads 6 and writes 1.
An agent's call through the MCP door checks the live grant instead: the session, the client, the resource link and the consent, 6 documents in the auth component, about 27 ms when nothing is cached. The library checks the grant once per call, also in reads. A revoked connection fails at its next call.
Measured live on a Convex deployment, the totals match: a page of three
projects read 8 documents (6 + 2), and a tool call with a request_id read 9
and wrote 3 (3 + 6 for the grant). In convex-test with the real auth
component, a tool call that asks a person reads 10 documents and writes 2:
4 + 6 for the grant. The summary function's reads of rows the call already
read are free.
What one active user costs
An example, priced at Convex's Professional plan on 2026-10-07. The cost of each call is measured on a deployment; the usage pattern is an assumption: one person on a team who manages projects and uses an AI assistant, on 22 working days a month.
| Per working day | Count | Function calls |
|---|---|---|
| Opens or reloads the app (6 live queries) | 10 | 60 |
| Live updates when teammates change something | ~60 re-runs | 60 |
| Own changes | 15 | 15 |
| Session refreshes (app open about 2 hours) | 8 | 53 |
| Agent tool calls through MCP, grant check included | 20 | 78 |
| Approvals and in-app agent runs | 4 | 28 |
That is about 6,500 function calls and 11 MB of database traffic a month, or about $0.016 at the plan's overage prices. The plan's included amounts cover several thousand such users. The library's own checks are a small part of it: a person's call reads what a hand-written secure function reads, and the agent's grant check adds about $0.002 a month. The model calls of an in-app agent are billed by the model provider and usually cost more than all of the Convex usage.
Two things grow with use: live updates multiply with the number of people who
watch the same data, so keep queries narrow and paginate; and the activity log
grows until housekeeping deletes rows older than a year.
Keep a budget
Write one budget test for each kind of call your application makes, as in Test your app. The test fails when a change reads more, for example a lookup per row instead of one per call. Raise the number on purpose, and say why in the commit.
Reduce the cost of your own operations
- Read rows by an index that starts with the field their rule checks. A query cannot skip rows, so a broad query reads more and fails on the first foreign row.
- Look up related rows once per call, not once per row.
- Paginate lists. A tool for agents pages too: it gets
cursorandlimit(1 to 100, 50 by default) instead of Convex's pagination options. - Keep plans short. Every row a plan lists is fingerprinted, and
approvereads it again to check that it did not change.