SUsuperglue
Tools

Run a tool

post/tools/{toolId}/run

Request

  • Base URL
    https://api.superglue.cloud/v1
  • Auth
    HTTP bearer

Path parameters

toolIdstring required

Request body

runIdstring

Optional pre-generated run ID. If not provided, server generates one. Useful for idempotency and tracking runs before they start.

inputsobject

Tool-specific input parameters

filesobject

Files made available to the tool, keyed by the input name used in expressions.

credentialsobject

Ephemeral secret names and values merged into the run context. These values are not saved. Prefer a saved credential and options.pinnedCredentials for reusable integrations.

includeStepResultDataboolean

Include each step's result data in a synchronous response.

stateFixtureobject

Seed sourceData.persistedState for this run instead of the tool's persistent state. A seeded run never reads or saves persistent state changes, so it can test warm-state behavior (watermarks, cursors, dedupe) without touching real state. To adopt a state permanently, use PUT /tools/{toolId}/state.

Example request

{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "inputs": {
    "query": "latest AI news",
    "maxResults": 5
  },
  "credentials": {
    "apiKey": "sk_live_abc123def456",
    "apiSecret": "secret_xyz789"
  },
  "stateFixture": {
    "lastSyncedAt": "2026-01-01T00:00:00Z"
  },
  "options": {
    "webhookUrl": "https://your-app.com/webhooks/superglue",
    "pinnedCredentials": {
      "salesforce": "cs_1a2b3c4d"
    },
    "requestSource": "frontend",
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Response

Tool execution completed (sync)

runIdstring required

Unique identifier for this run

toolIdstring required

ID of the tool that was executed

systemIdsstring[]

Systems used by the run.

status'running' | 'success' | 'failed' | 'aborted' required

Execution status:

  • running: Execution in progress
  • success: Completed successfully
  • failed: Failed due to error
  • aborted: Cancelled by user or system
toolPayloadobject

The inputs provided when running the tool

dataunknown
errorstring

Error message (only present when status is failed or aborted)

optionsobject

Execution options that were used for this run

requestSource'api' | 'frontend' | 'agent' | 'scheduler' | 'mcp' | 'tool-chain' | 'webhook' | 'cli'

Source identifier for where the run was initiated

traceIdstring

Trace ID for this run (for debugging and log correlation)

resultStorageUristring

Internal storage URI for full results, when separate result storage was used. Use GET /runs/{runId}/results to fetch the full data.

userIdstring

User who triggered this run

Example response

{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "toolId": "550e8400-e29b-41d4-a716-446655440000",
  "tool": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Web Search",
    "version": "2.1.0",
    "instruction": "Search the web for the given query and return relevant results",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": {
          "type": "string"
        },
        "maxResults": {
          "type": "integer",
          "default": 10
        }
      },
      "required": [
        "query"
      ]
    },
    "steps": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "config": {
          "url": "https://api.example.com/search",
          "method": "GET",
          "queryParams": {
            "q": "<<(sourceData) => sourceData.query>>",
            "limit": 10
          },
          "headers": {
            "Content-Type": "application/json",
            "Authorization": "Bearer <<(sourceData) => sourceData.credentials.apiKey>>"
          },
          "body": "{\"query\": \"<<(sourceData) => sourceData.query>>\"}",
          "pagination": {
            "type": "cursorBased",
            "pageSize": "50",
            "cursorPath": "meta.next_cursor",
            "stopCondition": "(response, pageInfo, sourceData) => !response.data.pagination.has_more || pageInfo.totalFetched >= sourceData.maxResults"
          },
          "systemId": "3f7c8d9e-1a2b-4c5d-8e9f-0a1b2c3d4e5f"
        },
        "instruction": "Fetch user details from the API",
        "dataSelector": "(sourceData) => sourceData.data.items"
      }
    ],
    "outputTransform": "(sourceData) => sourceData.map(item => ({ id: item.id, title: item.name }))",
    "folder": "integrations/payments"
  },
  "status": "success",
  "error": "Connection timeout after 30000 milliseconds",
  "stepResults": [
    {
      "http": {
        "statusCode": 200
      }
    }
  ],
  "requestSource": "api",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resultStorageUri": "s3://superglue-results/org123/runs/7f3e9c1a.json",
  "metadata": {
    "durationMs": 5234
  },
  "fileArtifacts": [
    {
      "fileKey": "report",
      "filename": "monthly_report.csv",
      "contentType": "text/csv",
      "size": 52480,
      "downloadUrl": "https://s3.amazonaws.com/bucket/org/run-files/runId/report.csv?X-Amz-Expires=3600"
    }
  ]
}

Changes

No recorded changes to this operation across all 1 revision of this API.