# 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.

**Required Scopes:** `INTEGRATION_USE`

## URL Parameters

```typescript
interface URLParameters {
  /** The human-readable ID of the workspace */
  workspace: string; // Example: "my-company"
  /** The hash ID of the integration */
  hash_id: string; // Example: "abc123def456"
}
```

## Body Parameters

```typescript
interface BodyParameters {
  /** The type of the execution; it selects the payload. MCP runs the `mcp` operation on the MCP server of the integration */
  type: "COMMAND" | "MCP";
  /** The MCP operation to run on the integration's MCP server. Required with type MCP */
  mcp?: McpExecRequest;
}
```

## Response Body

```typescript
interface ResponseBody {
  /** The type of the execution: COMMAND (a command in the target's language) or MCP (an operation on the integration's MCP server) */
  type?: "COMMAND" | "MCP";
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the execution */
  execution_id?: string;
  /** The ID of the target */
  target_id?: string;
  /** The type of the target */
  target_type?: "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";
  /** The hash ID of the integration the execution ran on (MCP executions) */
  integration?: string;
  /** User/member reference */
  invoker?: MemberView;
  /** User/member reference */
  cancelled_by?: MemberView;
  /** The ID of the proxy target used to tunnel the connection */
  proxy_target_id?: string;
  /** The executed command; for an MCP execution the operation as canonical JSON */
  command?: string;
  /** The date and time when the execution started */
  started_at?: string;
  /** The date and time when the execution finished */
  finished_at?: string;
  /** The status of the execution. One of: INPROGRESS, SUCCESSFUL, FAILED, CANCELLED */
  status?: string;
  /** 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) */
  failure_reason?: string;
  /** The exit code of the executed command */
  exit_code?: number;
  /** The size of the execution output in bytes */
  bytes_out?: number;
  /** Indicates if the execution output was truncated */
  truncated?: boolean;
  /** The error message if the execution failed */
  error_message?: string;
  /** The URL to fetch the execution log */
  log_url?: string;
}
```

## Type Definitions

```typescript
interface McpExecRequest {
  /** The MCP operation: `LIST_TOOLS` lists the name and description of each server tool, `GET_TOOL` returns one tool's full definition with its schemas, `CALL_TOOL` invokes a tool */
  operation: "LIST_TOOLS" | "GET_TOOL" | "CALL_TOOL";
  /** The tool name. Required for `GET_TOOL` and `CALL_TOOL`, not allowed for `LIST_TOOLS` */
  tool?: string;
  /** The tool arguments as a JSON object. Allowed only for `CALL_TOOL` */
  arguments?: object;
}

interface MemberView {
  /** API endpoint to GET this object */
  url?: string;
  /** Web URL to view this object in Buddy.works */
  html_url?: string;
  /** The ID of the user */
  id?: number;
  /** The name of the user */
  name?: string;
  /** The unique username of the user */
  username?: string;
  /** The avatar URL of the user */
  avatar_url?: string;
  /** The email address of the user */
  email?: string;
  /** Whether the user has admin privileges */
  admin?: boolean;
  /** Whether the user is workspace owner */
  workspace_owner?: boolean;
}

```

## Request Example

```bash
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"
  }
}'
```

## Response Example

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

```json
{
  "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"
}
```

---
Original source: https://buddy.works/docs/api/integrations/execs/create