Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.superglue.cloud/llms.txt

Use this file to discover all available pages before exploring further.

​
Installation

npm install @superglue/client

​
Initialization

import {
  configure,
  listTools,
  getTool,
  runTool,
  getRun,
  cancelRun,
  listRuns,
} from "@superglue/client";

// Configure before making any API calls
configure({
  baseUrl: "http://localhost:4000/api/v1",
  apiKey: "your-api-key",
});

​
Tools

​
listTools

List all available tools with pagination. 
import { listTools } from "@superglue/client";

const response = await listTools({
  page: 1,
  limit: 50,
});

if (response.status === 200) {
  const { data, page, total, hasMore } = response.data;

  for (const tool of data) {
    console.log(`${tool.id}: ${tool.name || tool.instruction}`);
  }

  console.log(`Page ${page}, Total: ${total}, Has more: ${hasMore}`);
}
Parameters:
  • page - Page number (default: 1)
  • limit - Items per page (default: 50)
Returns: List of Tool objects with pagination metadata

​
getTool

Get detailed information about a specific tool. 
import { getTool } from "@superglue/client";

const response = await getTool("my-tool-id");

if (response.status === 200) {
  const tool = response.data;

  console.log(`Tool: ${tool.name}`);
  console.log(`Steps: ${tool.steps.length}`);
  console.log(`Version: ${tool.version}`);
  console.log(`Instruction: ${tool.instruction}`);
}
Parameters:
  • toolId - Unique tool identifier
Returns: Tool object with full configuration

​
runTool

Execute a tool with inputs and options. 
import { runTool } from "@superglue/client";

const response = await runTool("my-tool-id", {
  inputs: {
    userId: "user_123",
    startDate: "2025-01-01",
  },
  options: {
    async: false,
    timeout: 60,
    webhookUrl: "https://your-app.com/webhook",
    mode: "prod", // or "dev" for sandbox credentials
  },
  credentials: {
    stripeApiKey: "sk_test_...",
    slackToken: "xoxb-...",
  },
});

if (response.status === 200 || response.status === 202) {
  const run = response.data;

  console.log(`Run ID: ${run.runId}`);
  console.log(`Status: ${run.status}`);

  if (run.status === "success" && run.data) {
    console.log("Result:", run.data);
  } else if (run.status === "running") {
    console.log("Run in progress...");
  }
}
Parameters:
  • toolId - Tool to execute
  • runRequest - Execution configuration:
    • inputs - Input data accessible in tool steps
    • options - Execution options:
      • async - If true, return 202 immediately and execute asynchronously
      • timeout - Request timeout in seconds (sync only)
      • webhookUrl - URL to POST results when complete
      • traceId - Custom trace ID for log tracking
      • mode - Execution mode: "prod" (default) or "dev" for sandbox credentials
    • credentials - Runtime credentials to override defaults
Returns: Run object with execution status and results Status Codes:
  • 200 - Tool executed synchronously (completed)
  • 202 - Tool executing asynchronously (in progress)
  • 400 - Invalid request
  • 409 - Concurrent execution limit reached
  • 410 - Tool deleted
  • 429 - Rate limit exceeded

​
Runs

​
getRun

Get the status and results of a tool execution. 
import { getRun } from "@superglue/client";

const response = await getRun("run_abc123");

if (response.status === 200) {
  const run = response.data;

  console.log(`Status: ${run.status}`);
  console.log(`Tool: ${run.toolId}`);

  if (run.status === "success") {
    console.log("Result:", run.data);
    console.log("Steps:", run.stepResults);
  } else if (run.status === "failed") {
    console.error("Error:", run.error);
  }

  console.log(`Duration: ${run.metadata.durationMs}ms`);
}
Parameters:
  • runId - Unique run identifier
Returns: Run object with status, results, and metadata Run Statuses:
  • running - Execution in progress
  • success - Completed successfully
  • failed - Failed due to error
  • aborted - Cancelled by user or system

​
cancelRun

Cancel a running tool execution. 
import { cancelRun } from "@superglue/client";

const response = await cancelRun("run_abc123");

if (response.status === 200) {
  console.log("Run cancelled successfully");
  console.log("Status:", response.data.status); // "aborted"
}
Parameters:
  • runId - Run to cancel
Returns: Updated Run object with aborted status

​
listRuns

List tool execution runs with filtering and pagination. 
import { listRuns } from "@superglue/client";

// List all runs
const response = await listRuns({
  page: 1,
  limit: 50,
});

// Filter by tool
const toolRuns = await listRuns({
  toolId: "my-tool-id",
  page: 1,
  limit: 50,
});

// Filter by status
const failedRuns = await listRuns({
  status: "failed",
  page: 1,
  limit: 50,
});

if (response.status === 200) {
  const { data, page, total, hasMore } = response.data;

  for (const run of data) {
    const status = run.status === "success" ? "✓" : "✗";
    console.log(`${run.runId}: ${status} - ${run.metadata.startedAt}`);
  }
}
Parameters:
  • page - Page number (default: 1)
  • limit - Items per page (default: 50)
  • toolId - Filter by tool ID (optional)
  • status - Filter by status: running, success, failed, aborted (optional)
Returns: List of Run objects with pagination metadata