Skip to main content

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

CallReadsWritesWhat they are
A page of a list query, 3 rows60user, organization, membership, and the 3 rows. The row rules add nothing
A mutation of one row under a tenant rule41user, 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)31user, organization, membership. The parent check reuses the role
A tool call with a request_id33user, organization, membership; the rate-limit window, the row, the activity row
The same call again (a retry that replays)61the same checks, the rate-limit window, and the stored activity row
A tool call that asks a person ('approve')42user, the row (for its tenant), membership, the row again for the request's fingerprint; the rate-limit window, the request
approve of a request104approver, 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 dayCountFunction calls
Opens or reloads the app (6 live queries)1060
Live updates when teammates change something~60 re-runs60
Own changes1515
Session refreshes (app open about 2 hours)853
Agent tool calls through MCP, grant check included2078
Approvals and in-app agent runs428

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 cursor and limit (1 to 100, 50 by default) instead of Convex's pagination options.
  • Keep plans short. Every row a plan lists is fingerprinted, and approve reads it again to check that it did not change.