Query a dataset

Search with an x402 payment or a subscription quota and read ranked source passages.

Queries search a dataset using vector similarity and full-text search. Results contain matching passages, relevance scores, and references to the source files.

Route	Authorization	Cost
`POST /{username}/{slug}`	Signed x402 payment, when offered by the dataset	Listed USDC price per successful query
MCP `ask`	Subscription (OAuth or API key), an x402 payment in `_meta`, or free when priced at 0	One question, from the quota or paid per question
`POST /api/agent/query`	Account connected through OAuth, or an API key	One query from the dataset subscription's quota

x402 query

The public dataset POST requires x402 payment. If x402 is enabled and the dataset is ready to query, a request without payment returns 402 with payment requirements. The client signs an authorization and retries with a PAYMENT-SIGNATURE header. After a successful search, quarry settles the payment and returns the results.

Request

POST /alice/sec-filings HTTP/1.1
Content-Type: application/json

{ "query": "revenue guidance for 2025", "top_k": 5 }

Field	Type	Constraints
`query`	string	Required, non-empty, max 2000 characters
`top_k`	integer	Optional, 1–20, default 5

Subscription query

Connect an account through OAuth and obtain its agent access token. The account needs a confirmed paid period with remaining quota. Replace the origin and dataset reference with your environment's values:

curl https://quarry.market/api/agent/query \
  -H "Authorization: Bearer $QUARRY_AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "slug": "sec-filings",
    "query": "revenue guidance for 2025",
    "top_k": 5,
    "request_id": "sec-filings-query-001"
  }'

MCP ask accepts the same fields. A regular login token is not valid for either agent route; use OAuth or an API key.

Field	Type	Constraints
`username`	string	Required creator handle, 1–60 characters
`slug`	string	Required dataset slug, 1–80 characters
`query`	string	Required, trimmed, non-empty, max 2000 characters
`top_k`	integer	Optional, 1–20, default 5
`request_id`	string	Required, 1–128 characters; letters, numbers, `_`, `.`, `:`, or `-`

On the HTTP route, Idempotency-Key can supply the request ID and takes precedence over request_id in the body. Use a new ID for a new query. Reuse the same ID and query parameters after a timeout or for an identical retry; IDs are scoped to the account and dataset, across connectors.

Response

Both query routes return this search result structure:

{
  "dataset": { "slug": "sec-filings", "name": "SEC filings 2025" },
  "query": "revenue guidance for 2025",
  "results": [
    {
      "chunk_id": "a84b2e07-034c-4b1f-97b5-90e34cb62f51",
      "content": "We expect revenue to grow by 8% to 10% in fiscal 2025.",
      "score": 0.87,
      "vector_score": 0.91,
      "text_score": 0.64,
      "rerank_score": 0.83,
      "filename": "acme-10k-2025.pdf",
      "chunk_index": 42,
      "heading": "Outlook",
      "heading_path": ["Item 7", "MD&A", "Outlook"],
      "page_start": 61,
      "page_end": 62
    }
  ]
}

Result fields

Field	Meaning
`chunk_id`	Identifier of the indexed chunk
`content`	Text of the matching passage, or chunk
`score`	Combined vector and full-text ranking score before optional reranking
`vector_score`	Similarity score from vector search
`text_score`	Score from full-text search
`rerank_score`	Score from the reranking model, or `null` when no rerank score is available
`filename`	Name of the source file
`chunk_index`	Position of the chunk within the indexed file
`heading`	Nearest extracted heading, or `null`
`heading_path`	Array of headings from the outermost section to the nearest heading; empty if unavailable
`page_start`, `page_end`	Page range in the source document; `null` if unavailable

Results follow the reranking model's order when it is available. Otherwise, they follow the combined search ranking. Use the returned order when selecting passages.

Subscription quota fields

Subscription responses also include quota and replayed. Example fields added to the result above:

{
  "quota": {
    "period_id": "97403395-606d-4aeb-9a2d-03f97baf363e",
    "subscription_id": "013147ee-fc30-4af7-9290-3373e1670630",
    "quota": 3000,
    "used": 1,
    "reserved": 0,
    "remaining": 2999,
    "resets_at": "2026-10-15T12:00:00+00:00"
  },
  "replayed": false
}

reserved counts requests in progress. remaining subtracts both used and reserved queries. quota can be null if the paid period is no longer active when the response is assembled.

Identical retries can return the saved result for 24 hours with replayed: true and current quota, without consuming another query. Different parameters with the same ID return IDEMPOTENCY_CONFLICT; an expired saved result returns RESULT_EXPIRED. A successful empty search still consumes one query.

x402 payment headers

Header	Direction	Content
`PAYMENT-REQUIRED`	402 response	Base64-encoded JSON payment requirements (`accepts` array: scheme, CAIP-2 network, asset, amount)
`PAYMENT-SIGNATURE`	Request	Base64-encoded signed payment authorization; the legacy `X-PAYMENT` header is also accepted
`PAYMENT-RESPONSE`	Successful paid response	Base64-encoded JSON with the settlement's transaction hash in `transaction`

Request validation errors, dataset precondition failures, rate limits, and SEARCH_FAILED responses do not settle a payment. See Error codes for retry guidance.