---
title: "List runs"
method: GET
path: "/runs"
tags: ["Runs"]
---

# List runs

`GET /runs`

## Request

- Base URL: `https://api.superglue.cloud/v1`
- URL: `https://api.superglue.cloud/v1/runs`
- Auth: HTTP bearer

## Query parameters

- `toolId` string
- `search` string
- `searchUserIds` string
- `startedAfter` string, date-time
- `status` 'running' | 'success' | 'failed' | 'aborted'
- `requestSources` string
- `executionKinds` string
- `userId` string
- `systemId` string
- `includeTotal` boolean
- `page` integer
- `limit` integer

## Response `200`

List of runs

- object
  - `data` Run[], required
    - `runId` string, required: Unique identifier for this run
    - `toolId` string, required: ID of the tool that was executed
    - `tool` Tool: A saved integration tool containing request and transformation steps.
      - `id` string, required
      - `name` string
      - `version` string: Semantic version string (major.minor.patch)
      - `instruction` string: Human-readable instruction describing what the tool does
      - `inputSchema` object: JSON Schema for tool inputs
      - `outputSchema` object: JSON Schema for tool outputs (after transformations applied)
      - `steps` ToolStep[], required: Ordered execution steps. May be empty when `outputTransform` is present.
        - `id` string, required: Unique identifier for this step
        - `config` union, required
          - RequestStepConfig: Configuration for a request step. Protocol is detected from URL scheme: - HTTP/HTTPS: Standard REST API calls with query params, headers, body - Postgres: postgres:// or postgresql:// URLs, body contains SQL query - FTP/SFTP: ftp://, ftps://, or sftp:// URLs, body contains operation details
            - `type` 'request': Optional type discriminator (defaults to request)
            - `url` string, required: Full URL including protocol. Examples: - HTTP: https://api.example.com/search - Postgres: postgres://user:pass@host:5432/database - FTP: ftp://user:pass@host:21/path - SFTP: sftp://user:pass@host:22/path
            - `method` 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS': HTTP method. Defaults to GET. For non-HTTP protocols, use POST.
            - `queryParams` object: URL query parameters (HTTP only). Supports template expressions with <<(sourceData) => ...>> syntax.
            - `headers` object: HTTP headers (HTTP only). Supports template expressions with <<(sourceData) => ...>> syntax.
            - `body` string: Request body (protocol-specific). Supports template expressions with <<(sourceData) => ...>> syntax. HTTP: Any content (JSON, XML, form data, etc.) Example: '{"query": "<<(sourceData) => sourceData.query>>"}' Postgres: JSON with query and optional params Example: '{"query": "SELECT * FROM users WHERE id = $1", "params": ["<<(sourceData) => sourceData.userId>>"]}' FTP/SFTP: JSON with operation, path, and optional content Example: '{"operation": "get", "path": "/data/file.csv"}' Example: '{"operation": "list", "path": "/data"}' Example: '{"operation": "put", "path": "/data/file.txt", "content": "<<(sourceData) => sourceData.fileContent>>"}'
            - `pagination` Pagination: Pagination configuration (HTTP/HTTPS only, not applicable to Postgres/FTP)
              - …
            - `systemId` string: Connection namespace used to resolve credentials
            - `captureHttpResponse` boolean: HTTP only. When true, the step envelope and step result include `http` with the response status code and lowercase headers. Defaults to false.
          - TransformStepConfig: Configuration for a transform step. Transform steps execute JavaScript code to reshape data between request steps without making external API calls.
            - `type` 'transform', required: Type discriminator for transform steps
            - `transformCode` string, required: JavaScript function that transforms sourceData. Format: (sourceData) => transformedData The function receives all previous step results and payload data.
        - `instruction` string: Human-readable instruction describing what this step does
        - `modify` boolean: Whether this step modifies data on the system it operates on
        - `dataSelector` string: JavaScript function to select data for loop execution. Format: (sourceData) => expression
        - `failureBehavior` 'fail' | 'continue': How to handle step failures (fail stops execution, continue proceeds to next step)
        - `outputFile` boolean: Promote files produced by this step as downloadable run artifacts.
      - `outputTransform` string: JavaScript function for final output transformation. Format: (sourceData) => expression
      - `folder` string: Folder path for organizing tools
      - `archived` boolean: Whether this tool is archived (if so, it will not be listed in the UI and cannot be run)
      - `createdByUserId` string: ID of the user who created the tool.
      - `createdAt` string, date-time
      - `updatedAt` string, date-time
      - `lastUsedAt` string, date-time
    - `systemIds` string[]: 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
    - `toolPayload` object: The inputs provided when running the tool
    - `data` unknown
    - `error` string: Error message (only present when status is failed or aborted)
    - `stepResults` StepResult[]: Per-step status and error details. A synchronous run response includes step data only when `includeStepResultData` is true; stored run records omit step data.
      - `stepId` string, required: ID of the step that was executed
      - `success` boolean, required: Whether the step completed successfully
      - `data` unknown
      - `error` string: Error message if the step failed
      - `stepFileKeys` string[]: File keys produced by this step.
      - `http` HttpResponseMetadata: Response metadata for an HTTP request step. Header names are lowercase; `set-cookie` values are arrays.
        - `statusCode` integer, required: HTTP response status code
        - `headers` object, required: Response headers keyed by lowercase name
        - `omittedHeaderCount` integer: Number of headers omitted from a size-bounded view
    - `options` object: 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
    - `traceId` string: Trace ID for this run (for debugging and log correlation)
    - `resultStorageUri` string: Internal storage URI for full results, when separate result storage was used. Use GET /runs/{runId}/results to fetch the full data.
    - `userId` string: User who triggered this run
    - `metadata` object, required
      - `startedAt` string, date-time, required
      - `completedAt` string, date-time: Only present when run has finished (success, failed, or aborted)
      - `durationMs` integer
      - `executionKind` 'full' | 'draft' | 'single-step'
      - `parentToolId` string: Parent saved tool for draft and single-step executions.
      - `warnings` string[]: Non-fatal run warnings, e.g. removed reserved inputs, persistent tool state write rejections, or concurrent-run conflicts.
      - `clientInfo` object
        - `name` string
        - `version` string
        - `userAgent` string
    - `fileArtifacts` FileArtifact[]: Files promoted as downloadable artifacts by the tool run. Only present when a step with `outputFile: true` 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.
      - `fileKey` string, required: Unique key identifying this file within the run
      - `filename` string, required: Original filename
      - `contentType` string, required: MIME type of the file
      - `size` integer, required: File size in bytes
      - `downloadUrl` string, uri: Pre-signed download URL, valid for 1 hour. Included in single-run and file-specific endpoints, omitted in list responses.
  - `page` integer, required
  - `limit` integer, required
  - `total` integer, required: Exact total unless `includeTotal=false`, in which case this is a lower bound.
  - `hasMore` boolean, required

## Other responses

- `400`: Invalid list query parameters
- `503`: Run search exceeded the database statement timeout

---

[API](https://skmtc.dev/superglue/apis/superglue-api.md) - [All operations](https://skmtc.dev/superglue/apis/superglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/superglue/apis/superglue-api/revisions/2d412a94bf09?raw)