---
title: "production_operation"
description: "Reconnect to a paid Hosted render, request cancellation, or collect its finished files."
canonical: "https://shotops.dev/docs/mcp/reference/production_operation"
last_updated: "2026-09-07"
shotops_mcp_version: "0.9.6"
result_contract_version: "2.0.0"
---
# production_operation

Reconnect to a paid Hosted render, request cancellation, or collect its finished files.

## What it does

- Writes
- Destructive
- Idempotent
- Account required

The addressable state of one production render or rendering bundle. It reports persisted progress in panels, estimates the rendering time left, accepts a cooperative cancellation request, and mints fresh short-lived download grants for a successful result without starting or charging the work again.

You can ask: “Reconnect to this production render and collect its finished result.”

There is deliberately no listing, Workflow-run lookup or diagnostics action, and no widget may call it directly.

Progress is reported twice over, in two units. `progress.panelsCompleted` and `progress.panelsTotal` count the panels you asked for, and `progress.estimatedRemainingSeconds` estimates the rendering left from the pace this operation is actually running at. `progress.completed` and `progress.total` count internal scheduling items — one per panel plus a bundle item plus a result item — so an eight-panel bundle is ten items. Report the panel numbers; the item counters are bookkeeping.

A full-resolution multi-panel render takes a few seconds per panel, so an eight-panel bundle is well over a minute. Each poll also returns a plain sentence beside the structured result, so an agent has something to tell you instead of leaving the wait unexplained.

## Input

- `action`stringrequired Read state, request cooperative cancellation, or obtain the terminal result. one of`get``cancel``result`
- `operationId`stringrequiredat least 1 character The opaque durable operation id returned by a production render.

## Result

- `ok`booleanrequired
- `count`numberoptional
- `panelPresetId`stringoptional
- `panelWidth`numberoptional
- `panelHeight`numberoptional
- `output`stringoptionalalways "urls"
- `locale`stringoptional
- `credits`objectoptional Credits this call spent from the account wallet, the balance left afterwards, and when that wallet is next topped up (ISO 8601; absent when no further refill is scheduled). Renders cost per panel; reads, saves, uploads and deletes are free, as is bundling panels that were already rendered.
  - `debited`numberrequired
  - `remaining`numberrequired
  - `refillAt`stringoptional
- `note`stringoptional Free-text advisories about THIS call, joined into one string. Written when the server did something you did not literally ask for or could not have known: a look/version fallback, an output-mode downgrade, a device this server cannot render, a `style.shotLook` a `look` overrode, or placement set by hand where a `style.layout` template would have produced the same composition. Never an error — the call succeeded. Read it, and act on it next call.
- `contract`objectrequired The versioned ShotOps result contract (#662): what ran, where, what it changed, what it cost, what it produced and — on a refusal — a typed failure over a closed code catalog. Structured content is authoritative; the prose beside it is a rendering of this block.
  - `contractVersion`stringrequired The version of THIS envelope, REPORTED. Compare it against the version you were written for. There is no version negotiation: no tool accepts a requested version, so this is never a refusal — it moves only when a field changes meaning, and additive fields never move it.
  - `status`stringrequired one of`succeeded``partial``failed``refused``accepted``queued``running``cancel_requested``cancelled`
  - `terminal`booleanrequired false ⟹ this operation is still running and will be reported again (#666).
  - `operation`objectrequired
    - `id`stringrequired Identity for THIS call, unique per invocation. Quote it in a bug report.
    - `tool`stringrequired The registered tool name that produced this result.
    - `kind`stringrequired one of`render``bundle``read``mutate``upload``delete``status`
    - `durable`objectoptional #666 domain handle for addressable long-running work. Absent from synchronous calls.
      - `operationId`stringrequired
      - `pollWith`stringoptional
  - `execution`objectrequired
    - `location`stringrequired Where the work RAN. `local` is the caller’s own machine over stdio. one of`local``hosted`
    - `inputModes`arrayrequired Every way this door accepts screenshots and assets. each item string one of`inline_base64``stored_ref``remote_url``local_path``project_stored`
    - `deliveryModes`arrayrequired Every way this door can hand a result back. each item string one of`inline_base64``signed_url``local_path``share_link`
  - `effects`objectrequired What this call DID to the world, independent of what it returned. Every flag is stated on every result, false included: an absent flag would be indistinguishable from an effect nobody thought to declare.
    - `networkFetch`booleanrequired This call fetched bytes from a host neither ShotOps nor the caller controls.
    - `upload`booleanrequired Caller bytes were uploaded into ShotOps storage.
    - `retainedStorage`booleanrequired Something survives this call in ShotOps storage.
    - `projectMutation`booleanrequired A saved project or its look history changed.
    - `publication`booleanrequired Something became reachable outside the account — a share link.
    - `deletion`booleanrequired Something was permanently removed.
  - `cost`objectrequired
    - `unit`stringrequiredalways "credit" Public cloud credits — the same unit every ShotOps surface quotes.
    - `model`stringrequired How this connection pays. `unmetered` is local stdio, which renders on the caller’s own machine; `anonymous_allowance` is the unsigned hosted taste. one of`metered``anonymous_allowance``unmetered`
    - `estimated`numberoptional What the call was expected to cost, before it ran.
    - `reserved`numberoptional Held against the wallet for the duration of the call (#666).
    - `released`numberoptional Given back — an unused reservation or a refund after a post-charge failure (#666).
    - `settled`numberoptional Actually taken. Absent when nothing was charged.
    - `balanceAfter`numberoptional The wallet’s public cloud credit balance once this call settled.
    - `refillAt`stringoptional ISO 8601. When the wallet is next topped up; absent when none is scheduled.
  - `progress`objectoptional Persisted monotonic durable-operation progress. Never inferred from transient render metadata. Relay `panelsCompleted`/`panelsTotal` and the estimate to the waiting user; the item counters are internal bookkeeping and do not match what they asked for.
    - `completed`integerrequiredmin 0 Internal scheduling items done — panels PLUS the bundle and result items. Do not quote this to a person.
    - `total`integerrequiredmin 0 Internal scheduling items in total. Larger than the panel count.
    - `panelsCompleted`integeroptionalmin 0 Panels finished, in the unit the caller asked in. THIS is the number to report.
    - `panelsTotal`integeroptionalmin 0 Panels this operation will produce — the count the user asked for.
    - `attempt`integerrequiredmin 0
    - `heartbeatAt`string or nulloptional
    - `estimatedRemainingSeconds`numberoptionalmin 0 Rough seconds of rendering left, from this operation’s own measured pace once a panel has landed. An estimate, not a deadline — say “about”. Absent when nothing is left to render.
  - `resolvedInput`objectoptional #661 — what the server actually resolved the request to, before any pixel was produced.
    - `snapshotId`stringoptional `psi_` + the first 32 hex of the fingerprint. Quote it in a bug report.
    - `fingerprint`stringoptional sha256 over every resolved fact. Equal fingerprints ⟹ equal production input.
    - `sources`arrayoptional One entry per source cell, resolved or not. `slot` is the cell the bytes came FROM — a shot id and coordinate on a saved project, an ordered slot label on a direct render. Never a filename, a ref or a URL. `origin` is absent exactly when `status` is not `resolved`: there is nothing the cell came from. each item object - `slot`stringrequired - `status`stringrequired one of`resolved``missing``ambiguous` - `origin`stringoptional one of`inline_base64``stored_ref``remote_url``local_path``project_stored`
    - `defaultsApplied`arrayoptional What the server chose because the caller said nothing. each item string
    - `overrides`arrayoptional What the caller said that changed the outcome. each item string
  - `readiness`objectoptional #665 — the readiness verdict and any waiver receipt.
    - `state`stringoptional `blocked` ⟹ nothing was delivered. `ready_with_findings` ⟹ delivered, and here is what to know. one of`ready``ready_with_findings``waived``blocked`
    - `policyVersion`stringoptional The readiness policy this verdict was computed under. A waiver granted under another one is rejected.
    - `findings`arrayoptional Every finding, with `code`, `waivable` and `digest`. A waiver names one id AND its digest; there is no wildcard and no code-level waiver. each item object - `id`stringrequired `rf_` + 24 hex. Quote it in a waiver. - `severity`stringrequired one of`info``warn``block` - `message`stringrequired - `target`objectrequired The exact shot, panel, locale, output or frames this finding is about. - `shotId`stringoptional - `panelIndex`numberoptional - `locale`stringoptional - `output`stringoptional - `captionLayer`numberoptional - `frames`arrayoptional each item number - `evidence`objectrequired Bounded redacted facts used to derive the finding and its digest.
    - `waivers`arrayoptional The waivers this call ACCEPTED. Pass these objects back verbatim to reuse them; a rebuilt one is rejected. each item object - `findingId`stringrequired - `findingDigest`stringrequired - `policyVersion`stringrequired - `waivedBy`stringrequired - `waivedAt`stringrequired - `code`stringrequired one of`source_identity_ambiguous``output_unsupported``output_omitted``look_exact_unavailable``no_panels``panel_invalid_png``panel_dimensions_invalid``renderer_failed``input_changed_during_run``panel_source_empty``locale_source_fallback``device_source_fallback``caption_inherited``caption_locale_fallback``look_source_fallback``caption_device_collision``caption_caption_collision``device_device_collision``caption_legibility_unresolved``scope_filtered``locale_not_live_on_apple``look_hold_inactive``caption_text_empty` - `reason`stringoptional
  - `artifacts`arrayoptional each item object - `id`stringrequired The opaque asset id from the custody registry (#663) — or, for `kind: "share"`, the link’s own token. Never a storage path, and never a signed URL. - `kind`stringrequired one of`panel``bundle``screenshot``share``project` - `delivery`objectrequired - `mode`stringrequired one of`inline_base64``signed_url``local_path``share_link` - `url`stringoptional THE ONE FIELD a signed URL may appear in. Nothing else in this envelope carries one. - `expiresAt`stringoptional ISO 8601, when the grant above stops working. - `bytes`numberoptional - `retainedUntil`stringoptional ISO 8601, when ShotOps stops keeping the artifact itself.
  - `failure`objectoptional Present exactly when `status` is `failed` or `refused`.
    - `code`stringrequired The closed failure code. Branch on this, never on the sentence. one of`invalid_input``unsupported_input``project_not_found``project_ambiguous``no_projects``version_not_found``resolution_incomplete``readiness_required``readiness_unmet``asset_not_found``asset_in_use``authentication_required``plan_required``trial_choice_required``quota_exhausted``anonymous_limit_reached``capability_denied``billing_unavailable``render_failed``storage_failed``persistence_failed``upstream_unavailable``payload_too_large``rate_limited``operation_not_found``idempotency_conflict``operation_unavailable``operation_not_ready``contract_version_unsupported``internal_error`
    - `phase`stringrequired How far the call got. `input` and `authorization` guarantee nothing was rendered, stored, written or charged. one of`input``authorization``resolution``reservation``execution``delivery``persistence`
    - `retryable`booleanrequired true ⟹ the identical call may succeed later with nothing changed.
    - `nextAction`stringrequired The one move that resolves this, machine-readable. one of`none``fix_input``choose_project``upload_assets``reduce_scope``sign_in``choose_plan``upgrade_plan``retry``wait_and_retry``poll_operation``upgrade_client``contact_support`
    - `details`objectoptional Bounded, redacted, code-specific facts (the offending field name, the candidate project ids, the required plan). Never a credential, a signed URL or screenshot bytes.
- `panels`arrayoptional each item one of 3 shapes 1`string` 2`ref` - `ref`stringrequired - `url`stringrequiredformat uri 3`position` - `position`integerrequiredmin 1 - `contentIndex`integerrequiredmin 1 - `mimeType`stringrequiredalways "image/png" - `delivery`stringrequired one of`image``resource_link` - `ref`stringoptional
- `filename`stringoptional
- `bundleId`stringoptional
- `panelCount`numberoptional
- `zipUrl`stringoptionalformat uri
- `zipRef`stringoptional
- `operationId`stringoptional
- `status`stringoptional one of`accepted``queued``running``cancel_requested``succeeded``failed``cancelled`
- `progress`objectoptional
  - `completed`numberrequired
  - `total`numberrequired
  - `panelsCompleted`numberoptional Panels finished — the number to report to the user.
  - `panelsTotal`numberoptional Panels this operation will produce.
  - `attempt`numberrequired
  - `heartbeatAt`string or nulloptional
  - `estimatedRemainingSeconds`numberoptional About how many seconds of rendering are left. An estimate — say “about”.
- `failure`anyoptional

## Example

That request maps to this call:

```
{
  "name": "production_operation",
  "arguments": {
    "action": "get",
    "operationId": "THE_OPERATION_ID"
  }
}
```

The same operation id, its persisted status, how many of your panels are finished with a rough estimate of the rendering left, and its reserved or settled cost.

## Access and cost

- Needs an account — specifically the same signed-in ShotOps account that owns the operation.
- Reads and cancellation requests spend no cloud credits. The originating render owns reservation and settlement.

## When it refuses

- **The id is absent, belongs to another account or its project access was revoked.**
  The same operation_not_found refusal is returned in every case.

- **The operation is still queued, running or cancelling.**
  The result action returns persisted state only; poll the same id later.

- **A retained final asset is no longer active.**
  Delivery fails without rerendering, restarting or charging again.

## Where this fits

- [Reconnect-safe production in automation](https://shotops.dev/docs/mcp/workflows/automation)

## What the agent is told

The title and description the server publishes on `tools/list` — this is the copy a model chooses between, reproduced verbatim.

Check or cancel a production operation

Reconnect to an addressable App Store screenshot render or rendering bundle after its original tool call returns. `get` reports persisted monotonic state and progress, `cancel` requests cooperative cancellation, and `result` returns the terminal render or bundle with freshly minted delivery grants. Relay every `get` to the user: say how many of THEIR panels are done (`progress.panelsCompleted` of `progress.panelsTotal`) and about how long is left (`progress.estimatedRemainingSeconds`) before you poll again. `progress.completed` and `progress.total` count internal scheduling items, not panels, so quoting them describes a job the user did not ask for. Missing, foreign and access-revoked ids are intentionally indistinguishable. There is no list, workflow-run lookup, delivery action or diagnostics surface.