---
title: "Execute an object tool"
method: POST
path: "/v1/object-tools/{tool-id}/execute"
tags: ["Object Tools"]
---

# Execute an object tool

`POST /v1/object-tools/{tool-id}/execute`

Execute a server-capable object tool on the specified object.
Supported tool types: action (agent action), server-command, server-script,
snmp-table, agent-table, agent-list, ssh-command, url.
Client-only tool types (command, file-download) are rejected with 400.

## Path parameters

- `tool-id` integer, required

## Request body

- object
  - `objectId` integer, required — ID of the target object to execute the tool on
  - `alarmId` integer — Optional alarm ID for macro expansion context
  - `inputFields` object — Optional input field values for macro expansion
  - `maskedFields` string[] — Optional list of input field names whose values must be masked in the audit log and in user-visible context such as the result table title for table tools (typically password-type fields). Names not present in inputFields are ignored.
  - `stream` boolean — If true and the tool generates output, execution starts asynchronously and a WebSocket token is returned for streaming output. Supported for tool types: action, server-command, server-script, ssh-command.

## Response `200`

Tool executed successfully (synchronous mode)

- union
  - ObjectToolTextResult
    - `type` 'text', required
    - `output` string, required — Text output from tool execution (agent action output, server command output, or script output with result)
  - ObjectToolTableResult
    - `type` 'table', required
    - `table` object, required — Table result from SNMP table, agent table, or agent list tool execution
      - `extendedFormat` boolean
      - `source` integer
      - `title` string — Table title
      - `columns` object[]
        - `name` string — Column name
        - `dataType` integer — Column data type code
        - `displayName` string — Column display name
        - `instanceColumn` boolean
        - `unitName` string
        - `multiplier` integer
        - `useMultiplier` integer
      - `data` object[]
        - `objectId` integer
        - `baseRow` integer
        - `values` object[]
          - `status` integer — Cell status code
          - `value` string — Cell value
  - ObjectToolNoResult
    - `type` 'none', required — Indicates tool executed successfully but produced no output
  - ObjectToolUrlResult
    - `type` 'url', required
    - `url` string, required — Expanded URL with all macros resolved

## Other responses

- `202` — Tool execution started in streaming mode. Connect to the returned WebSocket URL to receive output in real-time.
- `400` — Invalid request. Possible reasons: - Invalid or missing tool-id - Missing or invalid objectId - Tool type is client-only (command, file-download) - Tool is disabled - Incompatible object class for the tool type - SSH command target has no owning node (standalone access point, sensor without gateway)
- `403` — Access denied. Possible reasons: - User does not have access to the tool (tool ACL) - User does not have OBJECT_ACCESS_CONTROL on the target object (or on the owning node for SSH tools on interface/sensor/access point) - User does not have access to the specified alarm
- `404` — Not found. Possible reasons: - Object tool with the given ID does not exist - Target object with the given objectId does not exist - Script not found in library (for server-script tools)
- `500` — Execution failed. Possible reasons: - Database failure loading tool metadata - Cannot connect to agent - Command execution failed - Script execution failed - Table tool execution failed - SSH proxy not available
- `504` — Server command execution timed out.

---

[API](https://skmtc.net/netxms/apis/netxms-api.md) · [All operations](https://skmtc.net/netxms/apis/netxms-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/netxms/netxms-api/versions/14d93e5115dd/schema)