---
title: "Execute a CAP within a credit budget"
method: POST
path: "/capabilities/query"
tags: ["Capabilities"]
---

# Execute a CAP within a credit budget

`POST /capabilities/query`

## Request

- Base URL: `https://qveris.ai/api/v1`
- URL: `https://qveris.ai/api/v1/capabilities/query`
- Auth: HTTP bearer

Execute a CAP through capability-aware routing. `max_credits` is forwarded unchanged and excludes candidates whose upper-bound price cannot be proven within the budget. The response identifies the contract used by the actual execution.

## Request body

- union
  - object
    - `capability_id` string, required
    - `query` string
    - `parameters` object
    - `params` object
    - `session_id` string, nullable
    - `search_id` string, nullable
    - `run_id` string
    - `provider_id` string
    - `provider_ids` string[]
    - `max_response_size` integer
    - `max_credits` number: Maximum credits allowed for this execution. Candidates without a provable upper bound are excluded.
  - object
    - `capability_id` string
    - `query` string, required
    - `parameters` object
    - `params` object
    - `session_id` string, nullable
    - `search_id` string, nullable
    - `run_id` string
    - `provider_id` string
    - `provider_ids` string[]
    - `max_response_size` integer
    - `max_credits` number: Maximum credits allowed for this execution. Candidates without a provable upper bound are excluded.

## Response `200`

Successful Response

- PublicCapabilityQueryResponse
  - `execution_id` string, required
  - `capability_id` string
  - `parameters` object
  - `result` object
  - `success` boolean, required
  - `error_message` string, nullable
  - `billing` object
  - `cost` number, nullable
  - `credits_used` number, nullable
  - `remaining_credits` number, nullable
  - `contract_version` integer: Published CAP contract version.
  - `schema_hash` string: SHA-256 identity of the published CAP contract.

## Other responses

- `401`: Invalid API key
- `402`: Insufficient credits
- `403`: Delegation constraint rejected
- `404`: Account unavailable during credit settlement
- `408`: Capabilities query request timeout
- `422`: No candidate fits max_credits
- `500`: Capabilities query failed
- `503`: Capability routing unavailable

---

[API](https://skmtc.dev/qveris/apis/qveris-public-rest-api.md) · [All operations](https://skmtc.dev/qveris/apis/qveris-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/qveris/apis/qveris-public-rest-api/revisions/7b78aeef092a?raw)