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

# Run Shortcut from CSV

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

## Request

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

Runs the shortcut once per row of a CSV or XLSX file that has already been uploaded to Floqer, without the file's contents passing through the request. Use this instead of Run Shortcut Batch for files, and for anything above 1,000 rows — it streams the file server-side and has no row limit. Returns 202 with a `batch_id`; the runs appear on List Shortcut Runs filtered by that `batch_id` as the file streams, so an empty list right after this call means the import has not reached its first row yet. Columns are mapped by header name: `mapping` keys are the file's column headers, values are input `reference` values from Get Shortcut. Headers are read from row 1 — a header you name that is not there fails the import and reports which one, rather than running every row with shifted inputs. Columns you leave out of `mapping` are not sent; inputs with no column fall back to the shortcut's `defaultValue`, then to "".

## Path parameters

- `id` string, required

## Request body

- RunShortcutCsvBody: Body for Run Shortcut from CSV. The file must already be uploaded to Floqer; pass its object key.
  - `file_ref` string, required: Object key of the already-uploaded file, exactly as Floqer issued it. Not a URL — a URL is rejected. The file must have been uploaded by someone in your organization.
  - `mapping` object, required: Column header in the file -> input `reference` on the shortcut. References come from Get Shortcut's `input_schema[].reference` — the same keys Run Shortcut takes in `input_data`. Headers are read from row 1; naming a header the file does not have fails the import and reports which one. Columns omitted here are not sent, and inputs with no column fall back to the shortcut's `defaultValue`. Two columns may not map to the same input.
  - `sheet_name` string: XLSX only — which worksheet to run. Defaults to the first sheet in the workbook. Naming a sheet the workbook does not have fails the import.

## Response `202`

Default Response

- object
  - `status` integer
  - `message` string
  - `data` RunShortcutCsvData: Acknowledgement that the import was accepted and queued. Runs appear on List Shortcut Runs filtered by `batch_id` as the file streams.
    - `status` 'processing', required: Always `processing` — the import runs in the background.
    - `batch_id` string, uuid, required: The batch every run from this file shares. Poll `GET /api/v1/shortcuts/{id}/runs?batch_id=...`; an empty list means the import has not reached its first row yet, and a failure before the first row appears there as a single failed run carrying the reason.
    - `columns_mapped` integer, required: How many of the file's columns will be sent — the number of entries in `mapping`.

## Other responses

- `400`: Invalid request — `file_ref` is a URL rather than an object key, `mapping` is empty, or it names an input reference this shortcut does not have
- `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, or when `file_ref` does not belong to the caller's organization.
- `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)