# Get a tool

`GET /v1/tools/{tool}`

No API key needed. Without one, requests are limited per IP address. A key sent must be valid.

Fetch one tool: the input it takes, the output it returns, and each provider that can serve it.

`input_schema` and `output_schema` are JSON Schemas and are the same whichever provider serves the call. Each provider lists its price, the inputs it accepts (`values` is null when it accepts any value the input schema allows) and the optional outputs it returns. The schemas are null while the tool is not callable.

No API key is needed. Without one, requests are rate limited per IP address.

## Example request

cURL:

```bash
curl https://api.voxoria.ai/v1/tools/google.serp.organic
```

Python:

```python
import httpx

response = httpx.get(
    "https://api.voxoria.ai/v1/tools/google.serp.organic",
)
print(response.json())
```

TypeScript:

```ts
const response = await fetch("https://api.voxoria.ai/v1/tools/google.serp.organic");
console.log(await response.json());
```

MCP (`tools/call` params):

```json
{
  "name": "get_tool",
  "arguments": {
    "tool": "google.serp.organic"
  }
}
```

## Path parameters

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| `tool` | string | Yes |  | The tool's ID, such as `google.serp.organic`. |

## Response

### 200

The tool.

One tool in full: its input and output schemas and each provider that can serve it.

The schemas are null while the tool is not callable.

| Field | Type | Nullable | Description |
| --- | --- | --- | --- |
| `tool` | string | No | The tool's ID, as calls and quotes take it. |
| `name` | string | No | The tool's name. |
| `platform` | object | No | The platform the tool's data is about. |
| `platform.slug` | string | No | The platform's ID, as the `platform` filter takes it. |
| `platform.name` | string | No | The platform's name. |
| `category` | string | No | The kind of data it returns. One of `seo`, `social`, `enrichment`, `reviews`. |
| `callable` | boolean | No | Whether the tool can be called today. |
| `from_price_usd` | string | Yes | What one call costs at the cheapest provider. Null when no provider can serve it. |
| `input_schema` | object | Yes | The JSON Schema of a call's `input`. Null while the tool is not callable. |
| `output_schema` | object | Yes | The JSON Schema of a call's `output`. Null while the tool is not callable. |
| `providers` | array of object | No | Each provider that can serve it, with its price. |
| `providers.provider` | string | No | The provider's ID, as a call's `provider` takes it. |
| `providers.name` | string | No | The provider's name. |
| `providers.price` | object | No | What one call costs you when this provider serves it. |
| `providers.price.basis` | string | No | What a call is priced by. One of `per_call`, `per_success`, `per_result`, `per_call_and_result`, `free`. |
| `providers.price.unit_price_usd` | string | No | The price of one call, or of one `result_unit` under `per_result`. |
| `providers.price.max_price_usd` | string | Yes | The most one call can cost. Null when the price states no ceiling. |
| `providers.price.result_unit` | string | Yes | What one result is, under a basis priced by results. Null otherwise. |
| `providers.price.max_results` | integer | Yes | The most results one call is charged for. Null under a basis not priced by results. |
| `providers.price.minimum_price_usd` | string | Yes | The least one call costs under `per_result`. Null otherwise. |
| `providers.price.result_price_usd` | string | Yes | The price of each result under `per_call_and_result`. Null otherwise. |
| `providers.supported_inputs` | array of object | No | Each input the provider accepts. |
| `providers.supported_inputs.name` | string | No | The input's name in the tool's `input_schema`. |
| `providers.supported_inputs.values` | array of string or integer or number or boolean | Yes | The values the provider accepts. Null when it accepts any the schema allows. |
| `providers.optional_outputs` | array of string | No | The optional outputs the provider returns, by name, as a call's `require` takes them. |

### Example 200 response

```json
{
  "tool": "google.serp.organic",
  "name": "Search Google organic results",
  "platform": {
    "slug": "google",
    "name": "Google"
  },
  "category": "seo",
  "callable": true,
  "from_price_usd": "0.0214",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string"
      },
      "country": {
        "type": "string",
        "default": "us"
      }
    },
    "required": [
      "query"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "results": {
        "type": "array"
      },
      "related_questions": {
        "type": "array"
      },
      "related_searches": {
        "type": "array"
      }
    }
  },
  "providers": [
    {
      "provider": "example-provider",
      "name": "Example provider",
      "price": {
        "basis": "per_call",
        "unit_price_usd": "0.0214",
        "max_price_usd": null,
        "result_unit": null,
        "max_results": null,
        "minimum_price_usd": null,
        "result_price_usd": null
      },
      "supported_inputs": [
        {
          "name": "country",
          "values": [
            "us",
            "gb",
            "de"
          ]
        }
      ],
      "optional_outputs": []
    }
  ]
}
```

## Errors

| Status | Body | Description |
| --- | --- | --- |
| 400 | [Refused request](/docs/call-response.md#refused-request) | The request was refused. |
| 401 | [Refused request](/docs/call-response.md#refused-request) | An API key was sent and is wrong or revoked (`INVALID_AUTH_TOKEN`). |
| 404 | [Refused request](/docs/call-response.md#refused-request) | No tool has this ID (`MODEL_NOT_FOUND`). |
| 422 | [Invalid request](/docs/call-response.md#invalid-request) | The request is not valid (`VALIDATION`). |
| 429 | [Refused request](/docs/call-response.md#refused-request) | Too many requests without an API key from this IP address, or with this API key (`RATE_LIMITED`). |