---
type: api
title: Run a tool
description: **Spaces method and path for this operation:**
url: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-post-agent-builder-tools-execute
resource: https://www.elastic.co/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/operation/operation-post-agent-builder-tools-execute
products:
- Kibana
---
# Run a tool
- Server: `https://{kibana_url}`
## Paths
- `POST` `/api/agent_builder/tools/_execute`
- `POST` `/s/{space_id}/api/agent_builder/tools/_execute`
- [Api key auth](/elastic/docs-builder/docs/4371/api/doc/kibana-serverless/authentication#apikeyauth)
## Description
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Run a tool with parameters. Use this endpoint to run a tool directly with specified inputs and optional external connector integration. To learn more about Agent Builder tools, refer to the [tools documentation](https://www.elastic.co/docs/explore-analyze/ai-features/agent-builder/tools).
[Required authorization] Route required privileges: agentBuilder:read.
## Request Body
`application/json`
- `approvals` (object) — optional
Actions the tool run may take that would otherwise need a live user to approve them. Applies to this run and any sub-agents it spawns.
- `auto_approved_apis` (object) — optional
Destructive Elasticsearch or Kibana APIs the tool may call without a user confirmation, keyed by backend. A tool run has no live user to answer the confirmation prompt, so a destructive API is refused unless it is listed here.
- `elasticsearch` ([] string · max: 100) — optional
Elasticsearch APIs pre-approved for this run. Each entry is an exact identifier formed from the namespace and name (for example `indices.create`), a namespace wildcard (for example `indices.*`), or `*` for every Elasticsearch API.
- `kibana` ([] string · max: 100) — optional
Kibana APIs pre-approved for this run. Each entry is an exact identifier formed from the namespace and name (for example `alerting.delete-alerting-rule-id`), a namespace wildcard (for example `alerting.*`), or `*` for every Kibana API.
- `connector_id` (string) — optional
Optional connector ID for tools that require external integrations.
- `tool_id` (string) — required
The ID of the tool to execute.
- `tool_params` (map string to object) — required
Parameters to pass to the tool execution. See examples for details
## Response
Indicates a successful response
## Code Examples
#### Console
```console
POST kbn:/api/agent_builder/tools/_execute
{
"tool_id": "platform.core.search",
"tool_params": {
"query": "can you find john doe's email from the employee index?"
}
}
```
#### curl
```curl
curl \
-X POST "https://${KIBANA_URL}/api/agent_builder/tools/_execute" \
-H "Authorization: ApiKey ${API_KEY}" \
-H "kbn-xsrf: true" \
-H "Content-Type: application/json" \
-d '{
"tool_id": "platform.core.search",
"tool_params": {
"query": "can you find john doe's email from the employee index?"}
}
}'
```
## Response Examples
#### Execute builtin ES|QL tool
Example response calling built-in platform.core.execute_esql tool
```json
{
"results": [
{
"data": {
"esql": "FROM financial_trades | LIMIT 3"
},
"type": "query"
},
{
"data": {
"columns": [
{
"name": "account_id",
"type": "keyword"
},
{
"name": "execution_price",
"type": "double"
},
{
"name": "symbol",
"type": "keyword"
},
{
"name": "trade_type",
"type": "keyword"
}
],
"query": "FROM financial_trades | LIMIT 3",
"source": "esql",
"values": [
[
"ACC00179-1f91",
43.77000045776367,
"CVX",
"sell"
],
[
"ACC00407-0bbb",
660.4199829101562,
"V",
"buy"
],
[
"ACC00179-1f91",
440.3599853515625,
"KO",
"buy"
]
]
},
"tool_result_id": "xTpT",
"type": "esql_results"
}
]
}
```
#### Execute builtin tool
Example response calling built-in platform.core.get_document_by_id tool
```json
{
"results": [
{
"data": {
"content": {
"account_id": "ACC00271-fb5c",
"execution_price": 488.54,
"execution_timestamp": "2025-08-05T08:04:11.649855",
"last_updated": "2025-09-15T13:23:36",
"order_status": "executed",
"order_type": "market",
"quantity": 131,
"status_reason": "fully_filled",
"symbol": "EWL",
"trade_cost": 63998.74,
"trade_id": "TRD-20250805-0820a89f",
"trade_type": "sell"
},
"partial": false,
"reference": {
"id": "TRD-20250805-0820a89f",
"index": "financial_trades"
}
},
"type": "resource"
}
]
}
```
#### Execute custom ES|QL tool
Example response calling custom example-esql-tool tool
```json
{
"results": [
{
"data": {
"columns": [
{
"name": "trade_count",
"type": "long"
},
{
"name": "avg_price",
"type": "double"
},
{
"name": "symbol",
"type": "keyword"
}
],
"query": "FROM financial_trades | WHERE execution_timestamp \u003E= ?startTime | STATS trade_count=COUNT(*), avg_price=AVG(execution_price) BY symbol | SORT trade_count DESC | LIMIT ?limit",
"source": "esql",
"values": [
[
2115,
89.33911587329621,
"US_T_BOND_20YR"
],
[
2112,
104.20854155945055,
"INTL_CORP_ASIA_D"
],
[
2105,
89.93244177666526,
"INTL_CORP_EU_B"
]
]
},
"tool_result_id": "Voy8",
"type": "esql_results"
}
]
}
```
#### Execute index search tool
Example response calling custom example-index-search-tool tool
```json
{
"results": [
{
"data": {
"esql": "FROM financial_trades\n| WHERE execution_price \u003E 100\n| LIMIT 100"
},
"type": "query"
},
{
"data": {
"columns": [
{
"name": "account_id",
"type": "keyword"
},
{
"name": "execution_price",
"type": "double"
},
{
"name": "execution_timestamp",
"type": "date"
},
{
"name": "symbol",
"type": "keyword"
},
{
"name": "trade_type",
"type": "keyword"
}
],
"query": "FROM financial_trades\n| WHERE execution_price \u003E 100\n| LIMIT 100",
"source": "esql",
"values": [
[
"ACC00407-0bbb",
660.4199829101562,
"2020-09-25T11:06:08.687Z",
"V",
"buy"
],
[
"ACC00179-1f91",
440.3599853515625,
"2025-08-07T21:56:45.377Z",
"KO",
"buy"
],
[
"ACC00407-0bbb",
132.8800048828125,
"2020-11-19T04:39:13.655Z",
"JAP_JGB_10YR",
"sell"
]
]
},
"tool_result_id": "uE8y",
"type": "esql_results"
}
]
}
```