# Inspect

```text
POST /v1/inspect
```

The contract for one capability: input schema, output fields, the providers behind it, exact prices, billing conditions and health. Free. Always inspect (and surface the price) before a billable run.

## Request

```json
{"capability": "contact.find"}
```

Unknown capabilities return `capability_not_found` (404). For a [raw endpoint](/docs/api/endpoints), pass the provider and the endpoint instead:

```json
{"provider": "dataforseo", "endpoint": "/v3/serp/google/organic/live/advanced"}
```

That returns the provider's own contract (`input` with `pathParams`, `queryParams`, `body`, `bodyType`; `example`; `cost`; `health`; `wrapped_by`; a ready `run.cli`; `hints`). Unknown endpoints return `endpoint_not_found` (404).

## Response

```json
{
  "capability": "contact.find",
  "title": "Find a work email",
  "category": "contact",
  "status": "live",
  "sandbox": true,
  "description": "...",
  "input_schema": {"...": "..."},
  "output_fields": ["email", "confidence", "..."],
  "billing": {"...": "unmatched lookups are not billed"},
  "providers": ["...", "..."],
  "live_providers": ["..."],
  "platforms": ["..."],
  "offers": [ {"...": "one entry per provider, see below"} ],
  "starting_price": {"amount": "0.05", "currency": "USD"}
}
```

## Offers

Each entry in `offers` is one provider's version of the capability:

| Field | Notes |
| --- | --- |
| `provider` | provider slug |
| `executable` | whether routing will consider it right now (in production: live adapter required) |
| `wired` | a real adapter exists for this provider and capability |
| `verified` | the price is a measured margin over provider cost, not a published-rate estimate |
| `platforms` | platforms this offer covers (for social and ads capabilities) |
| `price` | `{amount, currency, note}`: the note says how the price was set |
| `pricing` | when metered: `base` plus `per_result` (and `default_limit`), or `by_platform` variants |
| `metrics` | measured `success_rate`, `latency_ms_p50`, `latency_ms_p95` and `sample_size` over the recent window |
| `health` | the verdict on those numbers: `healthy`, `stable`, `degraded`, `outage` or `unknown` |

## Billing conditions

`billing` states when a call is charged: some capabilities bill per call, some only bill on a match, metered ones bill base plus per-result. The [run](/docs/api/run) endpoint enforces exactly what inspect stated; an unbilled no-match releases the reservation and, on auto routing, falls through to the next provider.