Skip to main content
POST
/
tools
/
{toolId}
/
run
Run a tool
curl --request POST \
  --url https://api.superglue.ai/v1/tools/{toolId}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "inputs": {
    "query": "latest AI news",
    "maxResults": 5
  },
  "credentials": {
    "apiKey": "sk_live_abc123def456",
    "apiSecret": "secret_xyz789"
  },
  "options": {
    "async": false,
    "timeout": 60000,
    "webhookUrl": "https://your-app.com/webhooks/superglue",
    "mode": "prod",
    "requestSource": "frontend",
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}
'
{
  "runId": "7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b",
  "toolId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "success",
  "metadata": {
    "startedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "durationMs": 5234
  },
  "tool": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "steps": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "config": {
          "url": "https://api.example.com/search",
          "method": "GET",
          "type": "request",
          "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) => !response.data.pagination.has_more"
          },
          "systemId": "3f7c8d9e-1a2b-4c5d-8e9f-0a1b2c3d4e5f"
        },
        "instruction": "Fetch user details from the API",
        "modify": false,
        "dataSelector": "(sourceData) => sourceData.data.items",
        "failureBehavior": "fail"
      }
    ],
    "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"
      ]
    },
    "outputSchema": {},
    "outputTransform": "(sourceData) => sourceData.map(item => ({ id: item.id, title: item.name }))",
    "folder": "integrations/payments",
    "archived": false,
    "responseFilters": [
      {
        "id": "<string>",
        "enabled": true,
        "target": "KEYS",
        "pattern": "<string>",
        "action": "REMOVE",
        "name": "<string>",
        "maskValue": "<string>",
        "scope": "FIELD"
      }
    ],
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z"
  },
  "toolPayload": {},
  "data": {},
  "error": "Connection timeout after 30000 milliseconds",
  "stepResults": [
    {
      "stepId": "<string>",
      "success": true,
      "data": {},
      "error": "<string>"
    }
  ],
  "options": {},
  "requestSource": "api",
  "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "resultStorageUri": "s3://superglue-results/org123/runs/7f3e9c1a.json",
  "userId": "<string>",
  "executionMode": "prod",
  "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"
    }
  ],
  "important_notice": "<string>"
}

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.

Authorizations

​
Authorization
string
header
required

Static API key authentication using Bearer token scheme. Include your API key in the Authorization header: Authorization: Bearer YOUR_API_KEY

Alternatively, you can use the token query parameter to authenticate.

API keys can be generated in your superglue dashboard.

Path Parameters

​
toolId
string
required

Body

application/json
​
runId
string

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

Example:

"7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b"

​
inputs
object

Tool-specific input parameters

Example:
{
  "query": "latest AI news",
  "maxResults": 5
}
​
credentials
object

Runtime credentials for systems (overrides stored system credentials if provided). WARNING: These credentials are not persisted. Use systems for stored credentials.

Example:
{
  "apiKey": "sk_live_abc123def456",
  "apiSecret": "secret_xyz789"
}
​
options
object

Response

Tool execution completed (sync)

​
runId
string
required

Unique identifier for this run

Example:

"7f3e9c1a-2b4d-4e8f-9a3b-1c5d7e9f2a4b"

​
toolId
string
required

ID of the tool that was executed

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
status
enum<string>
required

Execution status:

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

"success"

​
metadata
object
required
​
tool
object

Full tool configuration that was executed

​
toolPayload
object

The inputs provided when running the tool

​
data
object

Tool execution result data. Only present in the sync response from POST /tools/{toolId}/run (200). Not stored in the run record — for async runs, use GET /runs/{runId}/results to fetch results from storage.

​
error
string

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

Example:

"Connection timeout after 30000 milliseconds"

​
stepResults
object[]

Per-step execution results for multi-step tools. Only present in the sync response from POST /tools/{toolId}/run (200). For async runs, use GET /runs/{runId}/results.

​
options
object

Execution options that were used for this run

​
requestSource
enum<string>

Source identifier for where the run was initiated

Available options:
api,
frontend,
scheduler,
mcp,
tool-chain,
webhook,
cli
Example:

"api"

​
traceId
string

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

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

​
resultStorageUri
string

Storage URI where full results are stored (enterprise feature). Present when the result was too large for the run record. Use GET /runs/{runId}/results to fetch the full data.

Example:

"s3://superglue-results/org123/runs/7f3e9c1a.json"

​
userId
string

User or end user who triggered this run

​
executionMode
enum<string>

The execution mode used for this run (which system credentials were used)

Available options:
prod,
dev
Example:

"prod"

​
fileArtifacts
object[]

File artifacts produced by the tool run. Only present when the tool produced file output. In list responses, includes metadata only (no downloadUrl). In single-run responses (GET /runs/{runId}), includes presigned download URLs (1 hour TTL). Use GET /runs/{runId}/files to get fresh download URLs.

​
important_notice
string

Upgrade notice shown to free-tier organizations