---
title: "Inspect capabilities by id"
method: POST
path: "/tools/by-ids"
tags: ["Tool Execution"]
---

# Inspect capabilities by id

`POST /tools/by-ids`

## Request

- Base URL: `https://qveris.ai/api/v1`
- URL: `https://qveris.ai/api/v1/tools/by-ids`
- Auth: HTTP bearer

Fetch full capability metadata for one or more tool ids. Inspect is free and returns the same capability shape as Discover, including parameter schema, verification evidence, provider access restrictions, examples, quality signals, and cost estimates. Clients must disclose restrictions before Call.

## Request body

- PublicToolsByIdsRequest
  - `tool_ids` string[], required: Capability ids returned by Discover.
  - `search_id` string: Search id that returned these capabilities, when available.
  - `session_id` string: Optional tracking and pricing-context identifier. It does not promise a cache hit.
  - `view` 'full' | 'lean': Response projection. `lean` trims per-capability metadata for model context; `full` or omitted returns the complete result shape.

## Response `200`

Successful Response

- PublicInspectResponse
  - `search_id` string, required
  - `total` integer, required
  - `results` PublicCapabilityResult[], required
    - `tool_id` string, required
    - `name` string
    - `tool_name` string
    - `description` string
    - `updated_at` string: Catalog update timestamp when provided by the source.
    - `provider_id` string
    - `provider_name` union: Provider display name as text or a locale-keyed text map.
      - string
      - object
    - `provider_description` string
    - `category` string
    - `categories` union[]: Categories/tags attached to the capability. Current responses return category objects; legacy responses returned plain strings.
      - union
        - PublicToolCategory: Category/tag attached to a capability.
          - `slug` string
          - `name` string
          - `description` string
        - string
    - `capabilities` PublicToolCapability[]: Standardized capability descriptors with coverage tags.
      - `id` string
      - `tag` PublicCapabilityTag[]
        - `id` string
        - `name` string
        - `type` string
        - `description` string
    - `region` string
    - `score` number
    - `why_recommended` string: Human-readable explanation of why this capability was recommended for the query. Returned by Discover.
    - `params` union: Provider parameter contract preserved for catalog inspection.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `parameters` union: Alternative public input contract when supplied by the provider.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `input_schema` union: Provider input schema used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `parameters_schema` union: Provider parameter schema used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `query_params` union: Provider query-parameter contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `body_params` union: Provider request-body parameter contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `requestBody` union: OpenAPI request body contract used by catalog verification.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `output_schema` union: Public output schema advertised by the capability when available.
      - object
      - unknown[]
        - unknown
      - string
      - number
      - boolean
    - `examples` object
    - `stats` PublicToolStats
      - `avg_execution_time_ms` number, nullable
      - `success_rate` number, nullable
      - `sample_count` integer
      - `quality_sample_count` integer
      - `metrics_sample_count` integer
      - `success_rate_sample_count` integer
      - `latency_sample_count` integer
      - `minimum_sample_count` integer
      - `success_rate_minimum_sample_count` integer
      - `latency_minimum_sample_count` integer
      - `data_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `quality_data_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `success_rate_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `latency_status` 'available' | 'insufficient' | 'stale' | 'unavailable'
      - `metric_window` string
      - `window` string
      - `window_label` string
      - `window_start` string, date-time
      - `window_end` string, date-time
      - `metrics_updated_at` string, date-time
      - `last_checked_at` string, date-time
    - `has_last_execution` boolean: Whether the capability has a recorded execution used as a bounded verification signal.
    - `expected_cost` string: Pre-call cost estimate returned by Discover/Inspect when available.
    - `cost` union: Legacy cost estimate. Prefer `expected_cost` and `billing_rule` for pre-call display.
      - number
      - string
    - `billing_rule` PublicBillingRule: Capability billing rule used for pre-call estimation. Final settlement is reflected in usage audit and credits ledger endpoints.
    - `calls_count` string
    - `verification_status` 'unverified' | 'verifying' | 'verified' | 'stale' | 'failed' | 'restricted', required
    - `verification` PublicCatalogVerification, required: Fail-closed catalog verification result. Only records with every required check passed, a valid test digest, and an unexpired 24-hour evidence window are verified.
      - `status` 'unverified' | 'verifying' | 'verified' | 'stale' | 'failed' | 'restricted', required
      - `policy_version` string, required
      - `required_checks` string[], required
      - `checks` PublicVerificationCheck[], required
        - `name` 'schema' | 'authentication' | 'description_contract' | 'provider_identity' | 'permissions' | 'freshness' | 'live_check', required
        - `status` 'missing' | 'verifying' | 'passed' | 'stale' | 'failed' | 'restricted', required
        - `checked_at` string, date-time, nullable
        - `evidence_digest` string, nullable
        - `reason` string, nullable
      - `verified_at` string, date-time, nullable
      - `expires_at` string, date-time, nullable
      - `test_run_digest` string, nullable
      - `quality_issues` string[], required
    - `execution_restrictions` PublicExecutionRestrictions, required: Additive readiness axes and action guidance. Discovery remains available for unknown or incomplete evidence. Explicit restrictions fail closed through blocked_actions. Missing provider restriction metadata is not an execution denial: a candidate with usable input and a fixed per-call catalog price may be called directly. The catalog price is an estimate, not a reserved quote; variable pricing still requires budget confirmation. Probe is optional unless preflight validation or a current quote is needed. Call remains subject to live authorization, availability, and billing checks.
      - `callable` boolean, required
      - `eligibility` 'unknown' | 'not_required' | 'required' | 'restricted', required
      - `license` 'unknown' | 'not_required' | 'required' | 'approved' | 'restricted', required
      - `regions` PublicRegionRestrictions, required
        - `allow` string[], required
        - `deny` string[], required
      - `commercial_use` 'unknown' | 'allowed' | 'conditional' | 'prohibited', required
      - `data_as_of` string, date-time, nullable
      - `warnings` string[], required
      - `technical` 'unknown' | 'ready' | 'blocked'
      - `authentication` 'unknown' | 'ready' | 'required' | 'blocked'
      - `region_status` 'unknown' | 'ready' | 'conditional' | 'blocked'
      - `freshness` 'unknown' | 'fresh' | 'stale' | 'failed'
      - `price_certainty` 'unknown' | 'estimated' | 'exact'
      - `confidence` number
      - `allowed_actions` string[]
      - `blocked_actions` string[]
      - `next_action` string
      - `retryable` boolean
    - `capability` string: Compact capability summary. Returned instead of the full descriptor fields when the request sets `view: routing`.
    - `cost_class` string: Coarse cost tier (e.g. `low`). Returned by the `routing` view.
    - `reliability` string: Coarse reliability grade (e.g. `A`). Returned by the `routing` view.
    - `as_of_support` boolean: Whether the capability supports as-of/point-in-time queries. Returned by the `routing` view.
  - `elapsed_time_ms` number
  - `remaining_credits` number, nullable
  - `error_message` string, nullable
  - `contract_warnings` string[]
  - `contract_features` string[]

## Other responses

- `401`: Unauthorized
- `429`: Too Many Requests
- `504`: Upstream timeout

---

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