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

# Export Shortcut Runs

`POST /api/v1/shortcuts/{id}/runs/export`

## Request

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

Starts a CSV export of one batch's runs and returns immediately with an `export_id`. The file is built in the background — poll **Get Shortcut Runs Export** until `status` is `completed`, then download `file_url`.

`batch_id` is the one returned by **Run Shortcut Batch** or **Import CSV for Shortcuts**, and the same id **List Shortcut Runs** filters by.

**Columns** are one per input field, then one per output field, then `status` — the same public field names the run endpoints return. They are fixed when the export starts, so a batch whose later runs failed still produces a rectangular file, and editing the shortcut afterwards cannot reshape an export already under way.

**One export at a time.** While an export of this shortcut is building for you, starting another returns the in-flight job with `created: false` instead of queueing a second build, so a retry is safe.

Exports are private to the API key's creator, and so are the runs themselves — you can only export a batch you ran. A batch with no runs is a 400 rather than an empty file.

Requires the `shortcuts:read` scope.

## Path parameters

- `id` string, required

## Request body

- ExportShortcutRunsBody: Body for Export Shortcut Runs. Names the batch whose runs become the CSV.
  - `batch_id` string, required: The batch to export, as returned by Run Shortcut Batch or Import CSV for Shortcuts. The same id List Shortcut Runs filters by. You can only export a batch you ran.
  - `file_name` string: Base name for the downloaded file, without extension. Defaults to `shortcut-runs`. Non-alphanumeric characters are replaced and the name is capped at 100 characters.

## Response `202`

Default Response

- object
  - `status` integer, required
  - `data` ShortcutExportJob, required: An export job. Poll Get Shortcut Runs Export until `status` is `completed` or `failed`.
    - `export_id` string, required: ID of this export. Pass it to Get Shortcut Runs Export to poll. Valid for 24 hours.
    - `status` 'running' | 'completed' | 'failed', required: `running` — queued or building. `completed` — `file_url` is ready. `failed` — see `error`. There is no separate queued state; a job is `running` from the moment it is accepted.
    - `progress` integer, required: Percent complete, 0-100. Reaches 100 only when `status` is `completed`.
    - `row_count` integer, required: Runs the export will contain, counted against the batch when the job was accepted — never an echo of the request.
    - `file_url` string: Time-limited download link, present only when `status` is `completed`. Minted fresh on every poll and valid for 15 minutes — it is a signed URL, so treat it as a secret and do not log or forward it.
    - `expires_at` string, date-time: When `file_url` stops working (UTC, ISO 8601). Present only alongside `file_url`.
    - `error` string: Why the export failed. Present only when `status` is `failed`.
    - `created` boolean: Export Shortcut Runs only. `true` when this call started the job; `false` when an export was already building for you on this shortcut and you were handed that one instead.
    - `started_at` string, date-time, required: When the job was accepted (UTC, ISO 8601).
    - `completed_at` string, date-time, required: When the job reached a terminal state (UTC, ISO 8601). `null` while still running.

## Other responses

- `400`: `batch_id` missing, or the batch has no runs
- `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
- `409`: An export is already in progress — retry shortly
- `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)