> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pomerado.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Run a tool

> Run a tool once and get its result from the job it starts.

Run a tool with its ID and an input that matches its input schema. Each run starts a job, which carries the result when it succeeds.

## From an MCP client

For a read tool, your agent calls `run_read_only_website_tool`, with the input as a JSON-encoded string:

```json theme={null}
{
  "tool_id": "tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
  "input": "{\"origin\": \"SFO\", \"destination\": \"JFK\", \"departure_date\": \"2026-11-20\"}"
}
```

The call usually returns the finished job in seconds. If the job is still running, follow its `next` (`get_job` with `wait_seconds`) instead of running the tool again.

For a write tool, use `run_website_tool` and send an `idempotency_key`.

## From the REST API

```bash theme={null}
curl https://api.pomerado.ai/v1/runs/read-only \
  -H "Authorization: Bearer $POMERADO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool_id": "tool_0f8e2d1c4b3a49e8a7f6e5d4c3b2a190",
       "input": {"origin": "SFO", "destination": "JFK", "departure_date": "2026-11-20"}}'
```

REST answers at once with `202` and the job. Read the job after the `Retry-After` seconds, until its status is `succeeded`, `failed` or `cancelled`:

```bash theme={null}
curl https://api.pomerado.ai/v1/jobs/job_6f1d0c2b3a4e45f8a9b7c6d5e4f3a2b1 \
  -H "Authorization: Bearer $POMERADO_API_KEY"
```

```json theme={null}
{
  "id": "job_6f1d0c2b3a4e45f8a9b7c6d5e4f3a2b1",
  "type": "run",
  "status": "succeeded",
  "result": {
    "flights": [
      { "airline": "Example Air", "departs_at": "08:05", "price": 289 }
    ]
  }
}
```

Save the result when you read it: it is kept until its first read, and at most 60 minutes after the job ends.

<Accordion title="Details">
  * Run a write tool with `POST /v1/runs` and an `Idempotency-Key` header, so a retry returns the same job instead of acting on the site twice. See [retries and idempotency](/guides/tools/retries-and-idempotency).
  * A job can stop with status `needs_input` to ask a question, such as a sign-in code. See [answer questions](/guides/jobs/answer-questions).
  * Instead of polling, get a [webhook](/guides/notifications/webhooks) when a job asks a question or finishes.
  * A tool that signs in uses your saved login for the site. See [logins](/guides/logins/overview).
</Accordion>

## Next

[Build a tool](/quickstart/build-a-tool) when none fits your task.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.