Get an operation

getOperation

GET /api/v1/operations/{id}

Scope, any one of: files.write files.move files.delete files.overwriteRate cost: 1

An operation, as it stands

While it is queued, running or cancelling: 202 with Retry-After, ask again after that many seconds. Once it has succeeded: 200, its result what it made (Content-Location names it). Once it has failed: the problem it ended with, at that problem’s own status (409 conflict, 403 download-blocked, 409 copy-incomplete, 409 source-remains, …), carrying the operation as operation. Once cancelled: 409 operation-cancelled, carrying it. Held for an approver (state pending_approval): 202 with a longer Retry-After until someone decides; declined, 403 change-declined; not decided in time, 409 change-expired; approved but the item changed since it was asked for, 412 changed-since-requested; approved but the share could not be opened as the person, 409 requester-not-connected (request it again). This is the polling pattern Power Automate and Logic Apps follow on their own. A copy is read under files.write, a move under files.move, a delete held for approval under files.delete and a version restore under files.overwrite. Another person’s or another app’s operation, or one your token has not the scope for, is the same 404 as one that does not exist.

Any one of these scopes is enough; which applies depends on the kind of operation being read.

Request

curl "$FOLDR/api/v1/operations/$ID" \
  -H "Authorization: Bearer $TOKEN"

$FOLDR is your site’s address (for example https://files.example.com) and $TOKEN is an access token. See Getting access.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes	The operation’s id (from the Location of the 202 that started it).

Responses

Status	Meaning	Body
200	It has succeeded: the operation, its result what it made (a copy or a move: the item, named by Content-Location; a delete: its deletion).	`application/json`: Operation
202	Still under way: the operation, its progress so far. Ask again after Retry-After.	`application/json`: Operation

200 response

Header	Description
`Content-Location`	Where to read what the operation made (the item at its canonical path). Absent when it made no item (a delete).

Operation:

Field	Type	Description
`id`	string (uuid)	Required. The operation’s id.
`kind`	string	Required. What it does: copy, move (to another share, or held for approval within one), delete or restore (a version restore). delete and restore are only ever operations held for approval. Known values: copy, move, delete, restore. Clients must accept values not listed here.
`state`	string, one of `pending_approval`, `queued`, `running`, `cancelling`, `succeeded`, `failed`, `cancelled`, `declined`, `expired`	Required. Where it has got to. pending_approval: held for an approver, nothing changed yet (approval says until when); queued: waiting to start; running: under way; cancelling: asked to stop, stopping at its next item; succeeded: done, result is what was made; failed: ended with the problem getOperation answers; cancelled: stopped, and what it had made removed (or, held for approval, withdrawn, nothing changed); declined: an approver said no, nothing changed; expired: nobody approved it in time, nothing changed.
`phase`	string or null	Required. A move’s phase: copying (every item is copied first; nothing has been removed from where it was, and a cancel removes the partial copy), then deleting (the copy is whole and proven, and the originals are being removed: too late to cancel). Null for a copy. Known values: copying, deleting. Clients must accept values not listed here.
`created_at`	string (date-time)	Required. When it was asked for (RFC 3339, UTC).
`started_at`	string or null (date-time)	Required. When a worker first started it; null while queued.
`finished_at`	string or null (date-time)	Required. When it finished; null until then.
`source`	OperationSource	Required. What is being copied, moved, deleted or restored.
`target`	OperationTarget or null	Required. Where it was asked to go: the path asked for. result.path is where it landed (on_conflict “rename” may have given it another name). Null for a delete or a restore.
`version_id`	string or null	Required. For a restore: the version asked for (one of listVersions’ ids). Null otherwise.
`progress`	OperationProgress	Required. How far it has got.
`result`	Item or null	Required. Once it has succeeded, what it made (the copy, the moved item at its new place, the restored file), at its canonical path; null until then, and for a delete (see deletion). A move that ended source-remains also has it: the whole copy it made.
`deletion`	Deletion or null	Required. A delete held for approval, once it has succeeded: what was deleted and where its storage keeps it now, as deleteItem answers. Null otherwise.
`approval`	OperationApproval or null	Required. For an operation held for an approver: how its approval stands. Null for one that never waited for approval.
`failures`	array of OperationFailure	Required. At most 100 items (failures_truncated says when there were more): for a copy that ended copy-incomplete, those it could not copy; for a move that ended source-remains, those still at the source. Empty otherwise.
`failures_truncated`	boolean	Required. True when more items failed than failures lists.

Example:

{
  "id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "kind": "string",
  "state": "pending_approval",
  "phase": "string",
  "created_at": "2026-11-04T09:30:00Z",
  "started_at": "2026-11-04T09:30:00Z",
  "finished_at": "2026-11-04T09:30:00Z",
  "source": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string",
    "kind": "file"
  },
  "target": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string"
  },
  "version_id": "string",
  "progress": {
    "items_done": 1,
    "items_total": 1,
    "bytes_done": 1,
    "bytes_total": 1
  },
  "result": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string",
    "name": "string",
    "kind": "file",
    "size": 1,
    "modified": "2026-11-04T09:30:00Z",
    "mime_type": "string",
    "export": {
      "mime_type": "string",
      "extension": "string"
    },
    "etag": "string",
    "read_only": false,
    "checked_out": {
      "by": {},
      "since": "2026-11-04T09:30:00Z"
    }
  },
  "deletion": {
    "deleted": {},
    "items": 1,
    "recoverable": "bin",
    "destination": "string",
    "where": "string"
  },
  "approval": {
    "status": "string",
    "expires_at": "2026-11-04T09:30:00Z",
    "decided_at": "2026-11-04T09:30:00Z"
  },
  "failures": [
    {
      "path": "string",
      "code": "string"
    }
  ],
  "failures_truncated": false
}

202 response

Header	Description
`Location`	Where to poll the operation: GET it until it answers anything but 202.
`Retry-After`	Seconds to wait before polling again.

Operation:

Field	Type	Description
`id`	string (uuid)	Required. The operation’s id.
`kind`	string	Required. What it does: copy, move (to another share, or held for approval within one), delete or restore (a version restore). delete and restore are only ever operations held for approval. Known values: copy, move, delete, restore. Clients must accept values not listed here.
`state`	string, one of `pending_approval`, `queued`, `running`, `cancelling`, `succeeded`, `failed`, `cancelled`, `declined`, `expired`	Required. Where it has got to. pending_approval: held for an approver, nothing changed yet (approval says until when); queued: waiting to start; running: under way; cancelling: asked to stop, stopping at its next item; succeeded: done, result is what was made; failed: ended with the problem getOperation answers; cancelled: stopped, and what it had made removed (or, held for approval, withdrawn, nothing changed); declined: an approver said no, nothing changed; expired: nobody approved it in time, nothing changed.
`phase`	string or null	Required. A move’s phase: copying (every item is copied first; nothing has been removed from where it was, and a cancel removes the partial copy), then deleting (the copy is whole and proven, and the originals are being removed: too late to cancel). Null for a copy. Known values: copying, deleting. Clients must accept values not listed here.
`created_at`	string (date-time)	Required. When it was asked for (RFC 3339, UTC).
`started_at`	string or null (date-time)	Required. When a worker first started it; null while queued.
`finished_at`	string or null (date-time)	Required. When it finished; null until then.
`source`	OperationSource	Required. What is being copied, moved, deleted or restored.
`target`	OperationTarget or null	Required. Where it was asked to go: the path asked for. result.path is where it landed (on_conflict “rename” may have given it another name). Null for a delete or a restore.
`version_id`	string or null	Required. For a restore: the version asked for (one of listVersions’ ids). Null otherwise.
`progress`	OperationProgress	Required. How far it has got.
`result`	Item or null	Required. Once it has succeeded, what it made (the copy, the moved item at its new place, the restored file), at its canonical path; null until then, and for a delete (see deletion). A move that ended source-remains also has it: the whole copy it made.
`deletion`	Deletion or null	Required. A delete held for approval, once it has succeeded: what was deleted and where its storage keeps it now, as deleteItem answers. Null otherwise.
`approval`	OperationApproval or null	Required. For an operation held for an approver: how its approval stands. Null for one that never waited for approval.
`failures`	array of OperationFailure	Required. At most 100 items (failures_truncated says when there were more): for a copy that ended copy-incomplete, those it could not copy; for a move that ended source-remains, those still at the source. Empty otherwise.
`failures_truncated`	boolean	Required. True when more items failed than failures lists.

Example:

{
  "id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
  "kind": "string",
  "state": "pending_approval",
  "phase": "string",
  "created_at": "2026-11-04T09:30:00Z",
  "started_at": "2026-11-04T09:30:00Z",
  "finished_at": "2026-11-04T09:30:00Z",
  "source": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string",
    "kind": "file"
  },
  "target": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string"
  },
  "version_id": "string",
  "progress": {
    "items_done": 1,
    "items_total": 1,
    "bytes_done": 1,
    "bytes_total": 1
  },
  "result": {
    "share_id": "0191f2c4-8a1e-7b52-9d3a-5c1e0b7a4d21",
    "path": "string",
    "name": "string",
    "kind": "file",
    "size": 1,
    "modified": "2026-11-04T09:30:00Z",
    "mime_type": "string",
    "export": {
      "mime_type": "string",
      "extension": "string"
    },
    "etag": "string",
    "read_only": false,
    "checked_out": {
      "by": {},
      "since": "2026-11-04T09:30:00Z"
    }
  },
  "deletion": {
    "deleted": {},
    "items": 1,
    "recoverable": "bin",
    "destination": "string",
    "where": "string"
  },
  "approval": {
    "status": "string",
    "expires_at": "2026-11-04T09:30:00Z",
    "decided_at": "2026-11-04T09:30:00Z"
  },
  "failures": [
    {
      "path": "string",
      "code": "string"
    }
  ],
  "failures_truncated": false
}

Errors

Every error is an application/problem+json document (ProblemDetails); branch on its type or code. See Errors.

Status	Problem types	When
400	`copy-into-itself` `invalid-path` `invalid-request` `move-into-itself`	One of: Copy into itself (copy-into-itself); Invalid path (invalid-path); Invalid request (invalid-request); Move into itself (move-into-itself).
401	`invalid-token`	Invalid token (invalid-token).
403	`change-declined` `download-blocked` `insufficient-scope` `legal-hold` `write-not-allowed`	One of: Change declined (change-declined); Download blocked (download-blocked); Insufficient scope (insufficient-scope); Legal hold (legal-hold); Not allowed for this app (write-not-allowed).
404	`not-found`	Not found (not-found).
409	`ambiguous-path` `approved-version-unavailable` `change-expired` `conflict` `copy-incomplete` `envelope-source` `folder-too-large` `not-a-file` `not-a-folder` `not-recoverable-here` `operation-cancelled` `published` `requester-not-connected` `source-remains` `storage-account-not-connected`	One of: Ambiguous path (ambiguous-path); Approved version unavailable (approved-version-unavailable); Change not approved in time (change-expired); Conflict (conflict); Copy incomplete (copy-incomplete); Out for signature (envelope-source); Folder too large (folder-too-large); Not a file (not-a-file); Not a folder (not-a-folder); Not recoverable here (not-recoverable-here); Operation cancelled (operation-cancelled); Published (published); Not connected when approved (requester-not-connected); Moved, but the original remains (source-remains); Storage account not connected (storage-account-not-connected).
412	`changed-since-requested`	Changed since requested (changed-since-requested).
413	`copy-too-large` `too-large`	One of: Copy too large (copy-too-large); Too large (too-large).
423	`checked-out`	Checked out (checked-out).
429	`rate-limited`	Too many requests (rate-limited).
500	`internal-error`	Internal error (internal-error).
503	`copy-interrupted` `share-unavailable` `share-unreachable` `write-failed`	One of: Copy interrupted (copy-interrupted); Share unavailable (share-unavailable); Share unreachable (share-unreachable); Write failed (write-failed).