---
title: "Find Idempotent Spreadsheet Job"
method: POST
path: "/api/spreadsheets/idempotent/lookup"
tags: ["Spreadsheets"]
---

# Find Idempotent Spreadsheet Job

`POST /api/spreadsheets/idempotent/lookup`

## Request

- Base URL: `https://api.shortcut.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.shortcut.ai/api/spreadsheets/idempotent/lookup`
- Auth: one of:
  - HTTP bearer
  - HTTP bearer
  - API key in cookie `shortcut_access_token`
  - HTTP bearer

Read the run already accepted for an idempotency key without creating work.

## Request body

- object
  - `prompt` string, required: Natural language task description
  - `initFile` string, uuid: Optional File ID for initial Excel file
  - `workbook` object: Read the input workbook from your workspace instead of uploading it. Mutually exclusive with initFile. The run reads the file as of dispatch and records its storage generation as the baseline for `apply`.
    - `workspacePath` string, required: Path of an .xlsx/.xlsm workbook in your global workspace, relative to the workspace root (for example "models/Acme DCF.xlsx").
  - `apply` 'review' | 'auto' | 'none': What to do with the result of a `workbook` run. "none" (default) only makes the result downloadable. "review" stores the baseline, result and a manifest in the review folder so the changes can be reviewed and merged. "auto" overwrites the workspace workbook if it is unchanged since the baseline and its filename extension matches the result format; otherwise it falls back to "review" and reports a warning in `apply.warnings`. For XLSM inputs, unavailable macro-format repair (including restricted storage egress) can therefore produce review artifacts instead of an automatic overwrite.
  - `reviewPath` string: Workspace-relative folder for review artifacts (baseline/result workbooks with format-dependent extensions, and review.json). Defaults to "platform-api/runs/<runId>". Only meaningful with apply "review" or "auto".
  - `automationRunId` string, uuid: Attribute this run to an automation run, so history and credits roll up to it.
  - `sourceWorkspace` union
    - object
      - `type` 'global', required
      - `id` 'global'
    - object
      - `type` 'file', required
      - `id` string, uuid, required
  - `contextFiles` string[]: Optional context file IDs: at most one .xls/.xlsx context workbook, in addition to an optional initial workbook. All attachment filenames must be unique, ignoring case.
  - `webhookUrl` string, uri: Optional URL to receive a POST callback when the job completes or fails. Requests are signed with your API key's webhook secret (see /verify) via X-Shortcut-Signature: sha256=<hmac-sha256>. Delivery is at least once with retries; deduplicate on the eventId body field (also X-Shortcut-Event-Id).
  - `originatingMode` 'plan'
  - `sourceThreadId` string: The conversation a Continue in Cloud handoff came from, so the same user can find its run from another device (`GET /api/spreadsheets?sourceThreadId=`).
  - `mode` 'action' | 'ask': Agent mode: "action" (default) reads and writes the spreadsheet, "ask" performs read-only analysis and review without modifying the spreadsheet
  - `model` string: Optional ShortcutXL model id or model pattern for this job. Use `GET /api/spreadsheets/models` for the standard catalog and actual submission default.
  - `speed` 'standard' | 'fast' | 'ultrafast': Response speed; Fast and Ultrafast require an exact supported Shortcut model ID and Fast mode access. Ultrafast requires GPT-6 Astra and uses more credits
  - `thinking` 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Optional ShortcutXL thinking/effort level for this job
  - `runtimeModelOverlay` object: Versioned ShortcutXL runtime model overlay, carried opaquely to the runtime
  - `preferCurrentModelForSubagents` boolean
  - `subagentModel` string
  - `workReferenceId` string, uuid: Organization work reference for usage reporting. Independent of project file access.
  - `workflowCategory` string: Explicit workflow category for usage reporting, such as Tax or Working papers.
  - `projectId` string, uuid: Optional Project ID whose source files are mounted read-only at /project. The writable /workspace mount remains the run-scoped file workspace.
  - `skills` string[]: Optional source-qualified skill IDs to apply to this job. Use `GET /api/spreadsheets/skills` and submit returned `id` values such as `default:commit`, `personal:my-skill`, or `team:{teamId}:team-skill`. Submit-time validation checks id shape and team authorization, but does not perform a GCS existence check. Passing one skill is recommended — combining multiple skills may produce unpredictable results.
  - `skillCatalog` boolean: Optional. When true, the run's agent sees every skill you can see in Shortcut (default, personal, and team skills, as listed by `GET /api/spreadsheets/skills`) as a catalog of names and descriptions, and reads a skill's instructions only if it decides to use one. The list is resolved when the run is dispatched, not at submit time, and grants no access beyond the skills the run can already read. It does not select or apply any skill; use `skills` to select one. Omitted or false keeps the default: only `skills` and built-in skills are available.
  - `retainConversation` boolean: Optional. Save this run's agent conversation as one of your Shortcut conversations so it can be reopened from chat history. When the run completes, its status includes `conversation`: an `available` locator or `unavailable`. Omitted runs keep the default unsaved session.
  - `debug` union: Optional debug mode. When enabled, API-v1 periodically persists bounded runner/session debug snapshots while the sandbox run is still active.
    - boolean
    - object
      - `enabled` boolean
      - `snapshotIntervalMs` integer

## Response `200`

Default Response

- object
  - `runId` string, required
  - `status` string, required

## Changes

- **2026-11-05** `4ae382e2c957`: 3 info
  - added the new optional request property `skillCatalog`
  - added the new optional request property `workReferenceId`
  - added the new optional request property `workflowCategory`
- **2026-10-29** `55894cf381d4`: 2 info
  - added the new optional request property `originatingMode`
  - added the new optional request property `sourceThreadId`
- **2026-10-22** `6dff11e9d66b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/shortcut/apis/shortcut-api/changes/api/spreadsheets/idempotent/lookup/post.md)

---

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