Agent subscriptions

A creator can offer a monthly dataset subscription with a fixed query quota. Subscriptions belong to your quarry account. OAuth connectors authorized by that account use the same quota, including when the client reuses its connection in another chat. Each dataset has its own subscription and quota.

Subscription availability depends on the quarry environment you use. If the Subscriptions page says payments are not enabled yet, checkout and authenticated agent queries are unavailable in that environment.

Connect your agent to your account. Either copy the MCP URL under Subscriptions → Connected agents into a client that supports Streamable HTTP and OAuth, then sign in and approve access; or create an API key for code. The URL under Connected agents (/api/agent/mcp) asks to sign in right away; /api/mcp asks only when a tool needs your account. Both serve the same tools.
Use search and get_dataset to find a dataset and read its price, quota and terms.
Call quote_access to check whether a question is already included.
If needed, call request_subscription with the dataset and offer IDs. Open the returned Checkout link, review the monthly commitment and pay with card or Link where available.
Call get_my_access or quote_access after payment. Once Stripe confirms the paid invoice, call ask to retrieve passages.

The connector may open a payment approval window if it supports MCP URL elicitation. Otherwise it returns a link. Creating a link does not charge you or grant access. The return from Checkout starts a payment-status check; the paid invoice must be confirmed before quota becomes available.

quote_access does not consume quota. Its status tells the agent what to do:

Status	Meaning
`included`	A paid period has queries remaining; use `ask`
`quota_exhausted`	The account has paid access but no queries remaining
`approval_required`	No paid access; a monthly offer is available to review
`payment_required`	No paid access or monthly offer; x402 is available
`not_authorized`	Neither subscription access nor a payment option is available

The response includes dataset_id, subscription_offer (or null), access (or null), and an x402 alternative (or null). Pass dataset_id and subscription_offer.id as dataset_id and offer_id to request_subscription.

Query quota

{
  "username": "publisher",
  "slug": "research",
  "query": "What changed in the latest report?",
  "top_k": 5,
  "request_id": "research-2026-09-10-001"
}

One successful request uses one query, including a search with no matching passages. The number of passages requested with top_k does not change the cost. Use a new request_id for each new request. For an identical retry, reuse the same ID: a saved response is available for 24 hours without using more quota. The same ID with a different query or top_k returns IDEMPOTENCY_CONFLICT. After the saved result expires, that ID returns RESULT_EXPIRED; a new query requires a new ID and uses quota.

Known search failures release their quota reservation. A request still running returns REQUEST_IN_FLIGHT. After a timeout or uncertain outcome, retry with the same ID to avoid consuming quota twice. IDs are shared across connectors for the same account and dataset. See the query reference for field limits and response details.

The quota resets with each paid monthly billing period. Unused queries do not roll over. quote_access returns the remaining quota and reset date. Queries in progress temporarily reserve quota, so remaining quota is quota - used - reserved.

When quota runs out, the agent receives QUOTA_EXHAUSTED. If the creator also offers x402, the response includes that payment option. Paying per query requires an explicit signed payment from your own wallet; Quarry never buys extra queries automatically. See Paying with x402.

Manage access

Open Subscriptions → My subscriptions to see usage and the paid period's end date in UTC.

Continue checkout resumes an unfinished payment.
Check payment status refreshes Stripe confirmation if access is still pending.
Manage billing opens Stripe's customer portal for invoices, payment-method updates, and cancellation.
Revoke, under Connected agents, removes that connector's access immediately.

Cancellation stops renewal; access continues until the paid period ends. A failed renewal does not extend it. Revoking a connector does not cancel the subscription or remove access for other authorized connectors. Changing a creator's public offer does not change an existing subscription's price, quota or terms.

If a creator withdraws a dataset from sale, paid subscribers keep access through authenticated MCP until their period ends. The dataset disappears from public discovery and cannot be purchased again during retirement.

Tools and HTTP routes

Signed in, the MCP server adds get_my_access, quote_access and request_subscription, and ask uses your quota. Delegated access permits reading subscriptions, consuming their quota and preparing a Checkout link. It cannot edit datasets, manage payment details or withdraw funds. A regular quarry login token is not an agent token: connect with OAuth, or use an API key.

API keys

Code that can't run an OAuth sign-in (LangChain, the Vercel AI SDK, scripts) can use an API key instead. Open Subscriptions, enter a name under API keys and click Create key. Copy it right away: it is shown once. Send it as a bearer token:

curl -H "Authorization: Bearer qk_..." https://quarry.market/api/agent/access

A key acts for your account on agent surfaces only (the MCP server and the /api/agent/* routes below), sharing your subscriptions and quotas like a connected agent. It never signs in to the quarry app. You can have up to 10 active keys; revoking one takes effect immediately.

With an MCP client library, pass the key as a request header, for example in Python with LangChain:

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "quarry": {
        "transport": "streamable_http",
        "url": "https://quarry.market/api/mcp",
        "headers": {"Authorization": "Bearer qk_..."},
    }
})
tools = await client.get_tools()

HTTP routes

These routes accept the same OAuth bearer token or an API key:

Route	Request
`GET /api/agent/access`	Your subscriptions and quotas
`POST /api/agent/quote`	`{ "username": "...", "slug": "..." }`
`POST /api/agent/subscription`	`{ "dataset_id": "...", "offer_id": "..." }`
`POST /api/agent/query`	The query object above; `Idempotency-Key` can supply `request_id`

The /api/mcp server also works without an account, for search and x402 payments. The public dataset POST /{username}/{slug} accepts x402 payments only when that payment option is enabled; it does not consume a subscription quota.

For creators

Open Subscriptions → Selling to connect Stripe. Once Stripe can accept card payments, open your dataset's Settings → Payment options. Choose Monthly subscription or Pay per query and monthly subscription, enter a monthly USD price, query quota and usage terms, then click Save payment options.

The navigation page manages account subscriptions and Stripe setup; each dataset's Settings controls its offer. See Publish your first dataset and Pricing and payouts for publishing and revenue details.