---
title: "List Shortcut Runs"
method: GET
path: "/api/v1/shortcuts/{id}/runs"
tags: ["Shortcuts"]
---

# List Shortcut Runs

`GET /api/v1/shortcuts/{id}/runs`

## Request

- Base URL: `http://localhost:3009`
- URL: `http://localhost:3009/api/v1/shortcuts/{id}/runs`
- Auth: HTTP bearer

Returns paginated runs for a shortcut. Filter by `mode` (single/batch) or `batch_id` to narrow results. Uses limit/offset pagination (default: 50 items, offset 0). For filtered queries `total` reflects the returned page's row count — paginate until a page returns fewer rows than `limit`.

## Path parameters

- `id` string, required

## Query parameters

- `limit` string
- `offset` string
- `mode` 'single' | 'batch'
- `batch_id` string
- `include_steps` 'true' | 'false'
- `origin_workflow_id` string
- `origin_data_id` string
- `origin_action_id` string

## Response `200`

Default Response

- object
  - `status` integer
  - `data` object
    - `runs` ShortcutRun[]
      - `id` string: Unique run identifier (UUID)
      - `app_id` string: ID of the shortcut this run belongs to
      - `workflow_id` string: ID of the underlying workflow that was executed
      - `data_id` string: ID of the data row created in the workflow for this run
      - `catalog_release_version` integer: Published source shortcut version used by this global run. Absent for ordinary shortcuts.
      - `credits_used` number, nullable: Actual net credits charged, after refunds. Null when unavailable.
      - `origin` object
        - `type` 'listing' | 'workflow' | 'api' | 'manual' | 'ackdb'
        - `workflow_id` string, nullable
        - `workflow_name` string, nullable
        - `data_id` string, nullable
        - `action_id` string, nullable
      - `steps` object[], nullable: Read-only step results from the executed version; requested with include_steps=true.
        - `id` string
        - `name` string
        - `action_name` string
        - `status` string
        - `error` string, nullable
        - `credits_used` number, nullable
        - `outputs` object[]
          - `id` string
          - `name` string
          - `value` unknown
          - `type` 'sectionList'
          - `columns` object[]: List columns from the executed version.
            - `responseId` string
            - `responseStructureId` string
            - `name` string
            - `type` string
      - `steps_error` string, nullable
      - `input_schema` InputField[]: Frozen input contract for this global run.
        - `reference` string: Snake_case identifier for this input field (derived from `name`) — use it as the key in `input_data` when running the shortcut
        - `name` string: Human-readable field name displayed in the shortcut UI
        - `description` string: Help text describing what value to provide for this field
        - `type` string: Field type: text, number, email, url, etc.
        - `required` boolean: Whether this field must be provided when running the shortcut
        - `defaultValue` unknown
      - `output_schema` OutputConfig[]: Frozen output contract for this global run.
        - `name` string: Human-readable name for this output field — the key for its value in a run's `output_data`
        - `description` string: Description of what this output contains
        - `display_column` string: Column header label shown in results tables
      - `user_email` string: Email of the user who triggered the run
      - `org_id` string: Organization ID
      - `input_data` object: Input values provided when the run was started, keyed by each field's `reference` from the shortcut's `input_schema`
      - `output_data` object, nullable: Output values produced by the workflow, keyed by each output field's `name` from the shortcut's `output_schema`. Null until the run completes.
      - `status` 'pending' | 'inProgress' | 'completed' | 'failed' | 'payloadFilled' | 'readyToBeReviewed' | 'checkingNextSource' | 'conditionNotMet' | 'error' | 'outOfCredits' | 'duplicate': Current execution status. Terminal states: completed, failed, error, outOfCredits. In-progress states: pending, inProgress, payloadFilled, readyToBeReviewed, checkingNextSource.
      - `error_message` string, nullable: Error details if the run failed. Null on success.
      - `created_at` string, date-time: When the run was created
      - `completed_at` string, date-time, nullable: When the run finished (completed or failed). Null while in progress.
    - `pagination` object
      - `limit` integer
      - `offset` integer
      - `total` integer

## Other responses

- `401`: Unauthorized — missing or invalid API key
- `403`: Forbidden. `code` says which permission refused: ROLE_FORBIDDEN (your role), INSUFFICIENT_SCOPE (the API key's scopes), WORKFLOW_FORBIDDEN (no access to the workflow), KEY_WORKFLOW_FORBIDDEN (the API key's workflow restriction).
- `404`: Shortcut not found
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.

---

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