---
title: "Run Shortcut"
method: POST
path: "/api/v1/shortcuts/{id}/run"
tags: ["Shortcuts"]
---

# Run Shortcut

`POST /api/v1/shortcuts/{id}/run`

## Request

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

Starts a shortcut run with the provided input data. The shortcut must be published. Key `input_data` by each field's `reference` value from the shortcut's `input_schema` (see Get Shortcut); unknown keys are rejected with a 400 listing the valid references. The run is asynchronous — poll the Get Shortcut Run endpoint for status and results.

## Path parameters

- `id` string, required

## Request body

- object
  - `input_data` object, required: Input field values keyed by each field's `reference` from the shortcut's `input_schema`

## Response `201`

Default Response

- object
  - `status` integer
  - `message` string
  - `data` object
    - `id` string
    - `data_id` string
    - `status` 'pending' | 'completed' | 'failed' | 'payloadFilled' | 'readyToBeReviewed' | 'checkingNextSource' | 'conditionNotMet' | 'error' | 'outOfCredits' | 'duplicate'
    - `created_at` string, date-time

## Other responses

- `400`: Invalid input fields
- `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). Also returned when the shortcut is unpublished.
- `404`: Shortcut not found
- `409`: Conflict — the shortcut is archived or has no published version (`code: "SHORTCUT_ARCHIVED"` / `"SHORTCUT_NOT_PUBLISHED"`)
- `429`: Too Many Requests — rate limit exceeded. Check `Retry-After` header for seconds until the limit resets.
- `503`: Service Unavailable — the shortcut's frozen graph is momentarily unreadable (`code: "SHORTCUT_GRAPH_UNAVAILABLE"`); retry

---

[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)