FAQ and troubleshooting

For agents

Do I need an account or API key?

For x402, use a wallet holding USDC on the endpoint's network; no quarry account or API key is needed. Read the contract with a free GET, then send paid queries with POST when that payment option is enabled.

For a monthly subscription, sign in to quarry and connect your agent to the MCP server with OAuth, or give it an API key. The subscription belongs to your account. Creators also need an account to publish.

I paid with Stripe but my agent still has no access

Check these points:

• Make sure the agent is connected to your account: signed in through OAuth (the URL under Subscriptions → Connected agents always asks), or sending your API key. Without either, ask has no subscription to use, and the public dataset POST never uses subscription quota.
• Sign in with the same quarry account that made the purchase.
• Open Subscriptions and use Check payment status if payment is still pending. Returning from Checkout alone does not grant access.
• Call quote_access to check the paid period and remaining quota. A failed payment, exhausted quota, or an ended period does not authorize another query.

See Agent subscriptions for the full connection flow.

Do my agents share the quota?

Yes, when each connector is authorized by the same quarry account. The quota is per dataset subscription, shared across those connectors. One successful query uses one unit, regardless of top_k. Identical retries with the same request ID reuse the saved result for 24 hours. See Query a dataset.

What happens when I cancel or revoke an agent?

Manage billing opens Stripe's portal, where cancellation stops renewal. Paid access continues until its period ends. Revoke immediately removes one connector's access; it does not cancel billing or affect other connected agents.

I keep getting 402 even though I'm sending a payment

If the body contains SUBSCRIPTION_REQUIRED and no x402 challenge, use the authenticated subscription flow instead. For x402, check the payment requirements returned by the endpoint:

• Sign on the required network. A Base authorization cannot pay a Base Sepolia endpoint, or the reverse.
• Hold enough of the specified USDC asset to cover amount. Both are listed in the accepts array of the base64-encoded PAYMENT-REQUIRED header.
• Use an authorization that is still valid and has not already settled. If the price changed, sign a new authorization for the current requirements.

For testnet USDC, use Circle's faucet. See Paying with x402 for the full request flow.

What does a 409 mean?

Read error.code to identify the cause:

• PAYOUT_NOT_CONFIGURED: the creator's payout address is missing or invalid.
• DATASET_EMPTY: the dataset has no indexed content.
• PAYMENT_IN_FLIGHT: the payment is locked, usually by another request still in progress. Wait for that request's result before retrying.
• REQUEST_IN_FLIGHT: a subscription query with this request ID is still running.
• IDEMPOTENCY_CONFLICT: that subscription request ID was used with different parameters.

See Error codes for retry guidance and subscription checkout errors.

How much does a query cost?

The creator sets the price. For x402, read payment.price_usdc in the free discovery contract, then check the payment requirements returned by POST. Those requirements use the current price even if the discovery response is cached. The demo endpoint costs 0.001 USDC.

For a subscription, the offer lists its monthly USD price, query quota, and usage terms. Each query consumes quota, with no automatic overage charge. Quota resets for each new paid monthly period; unused queries do not roll over.

How are results ranked?

Search combines vector similarity with full-text matching. When configured, a reranking model reorders the candidate passages. Each result includes its relevance scores, source filename, and available headings and page numbers. See Query a dataset.

Is my query private?

quarry receives your query to run the search. For successful subscription queries and settled x402 queries, up to the first 500 characters are recorded in query records. Dataset creators can review settled x402 queries alongside the payer's wallet address; the payment transaction is also public on the blockchain. Subscription query records are associated with your quarry account. Paying through Stripe does not create an x402 transaction.

For creators

Why can't I publish?

Your dataset must be ready and contain at least one indexed chunk. Publishing with x402 also requires a ready payout wallet. Publishing with subscriptions only requires an active monthly offer and a ready Stripe account instead. Check the selected mode in Settings → Payment options. See Publish your first dataset.

When do I receive the money?

For x402, USDC goes to your payout wallet after each successful query is settled. You can withdraw an available balance of at least 0.01 USDC to an external address. See Pricing and payouts for withdrawal requirements and fees.

For subscriptions, payments go to your connected Stripe account. Bank payouts are managed in Stripe. Subscriptions → Selling shows gross paid USD invoices separately from your USDC balance.

Where do I set the subscription price and quota?

Open the dataset's Settings → Payment options. Choose Monthly subscription or Pay per query and monthly subscription, fill in the price, quota, and usage terms, and save. Subscriptions → Selling is where you connect Stripe and review sales across datasets.

If saving is disabled, read the availability message: either monthly payments are not configured for this environment, Stripe onboarding is incomplete, or the dataset is retiring. See Publish your first dataset.

My file is stuck in indexing

Large files and scanned PDFs can take several minutes to index. quarry retries failed jobs up to three attempts per file and periodically recovers interrupted jobs.

If the file shows Error, open it to read the error message. Correct the source file if needed, then retry indexing from the dataset page. Reindexing the entire dataset has a five-minute cooldown.

Can I change the price later?

Yes. A new x402 price applies to new query requests; cached discovery contracts and catalog listings can take longer to update. Subscription price, quota, and usage-term changes apply to new subscribers. Existing subscriptions keep their original offer.

Can I unpublish a dataset with subscribers?

Yes. Unpublishing retires it: new sales stop, renewals are canceled, and paid subscribers keep access until their periods end. Content remains protected while subscriptions are open or paid access remains. Once those end, use Return to draft to edit or delete the dataset.

Why does a file ask me to reindex for inspection?

Older indexed files may not have the data required by the new Document, Markdown, and JSON inspection views, or the corrected PowerPoint chunk locations. Reindex the file to generate it. Source highlights are available only when the parser supplies compatible locations; missing highlights do not mean the extracted text is unavailable. See Inspect a file.

What file types can I upload?

PDF, Microsoft Office and OpenDocument files, EPUB, EML email, text and data files, and images. The creator guide lists the supported formats and explains how their content is indexed.