Agent tools

A tool is a model of modality tool: web search, fetching a page, enriching a person or a company, and SEO and market data. A tool run is a job. It answers 202 Accepted, runs in the background, and you poll it until it finishes.

Run a toolCopy Anchor Link

curl https://api.opinference.com/v1/tools/runs \
  -H "Authorization: Bearer $OP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: search-1" \
  -d '{"tool": "exa/search", "input": {"query": "open-source inference gateways"}}'

input must be a JSON object, and the tool refuses one it cannot use with 400 invalid_request. Send an Idempotency-Key so that a retried request does not start a second run.

The runCopy Anchor Link

{
  "id": "job_...",
  "object": "tool.run",
  "tool": "exa/search",
  "status": "succeeded",
  "output": [
    {
      "url": "https://...",
      "url_expires_at": "2026-10-20T13:00:02Z",
      "type": "application/json",
      "bytes": 4210
    }
  ],
  "usage": { "units": { "calls": 1, "results": 10 } },
  "created_at": "2026-10-20T12:00:00Z",
  "completed_at": "2026-10-20T12:00:02Z"
}

status is a job state: queued, processing, succeeded, failed or canceled. output is a signed link to one JSON file that holds the tool's result. Download it before the link expires.

When a tool finds nothing, the run still succeeds, with "outcome": "no_match". That is an answer, not an error, and it is billed as a call with no results.

PricingCopy Anchor Link

A tool is priced per call and per result. Where the tool reports its own charge, you are billed that charge plus the platform fee, so the listed price is typical rather than a cap. Your balance holds the worst case for the run while it runs, and settles to the real charge when it finishes.