Run integration execution

POST
/workspaces
/:workspace
/integrations
/:hash_id
/execs

Run a one-shot execution on the integration. type is required and selects the payload: MCP runs the mcp operation on the MCP server of the integration and returns the response in the execution log as JSON.

Request

REQUIRED SCOPES

INTEGRATION_USE

URL PARAMETERS

workspacerequiredstring

The human-readable ID of the workspace

Example: "my-company"

hash_idrequiredstring

The hash ID of the integration

Example: "abc123def456"

BODY PARAMETERS

typerequiredstring enum

The type of the execution; it selects the payload. MCP runs the mcp operation on the MCP server of the integration

Allowed enum:

COMMAND,

MCP

mcpMcpExecRequest

The MCP operation to run on the integration's MCP server. Required with type MCP

Response

RESPONSE BODY

typestring enum

The type of the execution: COMMAND (a command in the target's language) or MCP (an operation on the integration's MCP server)

Allowed enum:

COMMAND,

MCP

urlread-onlystring

API endpoint to GET this object

html_urlread-onlystring

Web URL to view this object in Buddy.works

execution_idstring

The ID of the execution

target_idstring

The ID of the target

target_typestring enum

The type of the target

Allowed enum:

FTP,

SSH,

MATCH,

MATCH_ID,

VULTR,

DIGITAL_OCEAN,

UPCLOUD,

GIT,

ARTIFACT_VERSION,

GKE,

EKS,

AKS,

DOKS,

K8S_CLUSTER,

EC2,

AGENT,

SANDBOX,

MYSQL,

PROJECT_REPO,

POSTGRESQL,

MONGO,

MSSQL,

RDS_MSSQL,

CLICKHOUSE,

RDS_MYSQL,

RDS_POSTGRESQL

integrationstring

The hash ID of the integration the execution ran on (MCP executions)

sandboxstring

The ID of the sandbox the command ran in (sandbox executions)

runtimestring enum

The runtime the command ran with (sandbox executions)

Allowed enum:

BASH,

JAVASCRIPT,

TYPESCRIPT,

PYTHON

invokerMemberView

User/member reference

cancelled_byMemberView

User/member reference

proxy_target_idstring

The ID of the proxy target used to tunnel the connection

commandstring

The executed command; for an MCP execution the operation as canonical JSON

started_atstring

The date and time when the execution started

finished_atstring

The date and time when the execution finished

statusstring

The status of the execution. One of: INPROGRESS, SUCCESSFUL, FAILED, CANCELLED

failure_reasonstring

Platform-level reason a FAILED execution failed (absent for an ordinary non-zero exit): TIMEOUT (hard time cap reached), SPAWN_FAILED (execution could not be started), BASTION_FAILED (SSH bastion tunnel failed)

exit_codeinteger

The exit code of the executed command

bytes_outinteger

The size of the execution output in bytes

truncatedboolean

Indicates if the execution output was truncated

error_messagestring

The error message if the execution failed

log_urlstring

The URL to fetch the execution log

Last modified on Oct 20, 2026

List integration executions Get integration execution

Examples

MCP list tools request MCP tool call request

Example: MCP list tools request

curl -X POST "https://api.buddy.works/workspaces/:workspace/integrations/:hash_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "MCP",
  "mcp": {
    "operation": "LIST_TOOLS"
  }
}'

Example: MCP tool call request

curl -X POST "https://api.buddy.works/workspaces/:workspace/integrations/:hash_id/execs" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "MCP",
  "mcp": {
    "operation": "CALL_TOOL",
    "tool": "search_issues",
    "arguments": {
      "query": "is:open label:bug"
    }
  }
}'

EXAMPLE RESPONSE

{
  "url": "https://api.buddy.works/workspaces/my-workspace/integrations/eXaMpLeHaSh/execs/0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90",
  "log_url": "https://api.buddy.works/workspaces/my-workspace/integrations/eXaMpLeHaSh/execs/0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90/log",
  "execution_id": "0f7c2d51-4a8e-4f0b-9d7e-3c1b2a6e5f90",
  "integration": "eXaMpLeHaSh",
  "type": "MCP",
  "invoker": {
    "url": "https://api.buddy.works/workspaces/my-workspace/members/1",
    "id": 1,
    "name": "John Doe"
  },
  "command": "{\"operation\":\"LIST_TOOLS\"}",
  "started_at": "2026-05-28T08:00:09.820Z",
  "status": "INPROGRESS"
}

STATUS

200 Execution accepted and started; row carries `status: RUNNING` until poll endpoints flip to terminal