API reference

Inspect

POST /v1/inspect: a capability's schema, providers and exact price, or a raw endpoint's contract and cost model.

POST /v1/inspect

The contract for one capability: input schema, output fields, the providers behind it, exact prices, billing conditions and health. Free. Inspect before the first run of a capability: its input schema is the source of truth, and its offers are what the run will be priced at.

Request

{"capability": "contact.find"}

Unknown capabilities return capability_not_found (404). For a raw endpoint, pass the provider and the endpoint instead:

{"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

{
  "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
`health`	the verdict (`healthy`, `stable`, `degraded`, `outage` or `unknown`) and `latency_ms_p50`, the typical latency in milliseconds

Called with a key, the prices are your workspace's own, after any plan or negotiated rate, and a run's quote, hold and max_cost check use the same numbers. discover and the catalog pages show list prices.

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 endpoint enforces exactly what inspect stated; an unbilled no-match releases the reservation and, on auto routing, falls through to the next provider.

Previous
Discover Next
Run

Reading this as an agent? This page as markdown: /docs/api/inspect.md · every page: /docs/llms.txt