# Operation status

Source: https://neondeerdata.com/docs/api/operations/

Follow accepted work through completion and inspect individual outcomes.

The APIs on this page require alpha access for your organization. App availability and API access are separate. [Check access and permissions](https://neondeerdata.com/docs/api/permissions/).

## Request

```http
GET /v1/operations/{operation_id}

```

Gets the status of work this API key started, such as a scan, a merge or a task change. Poll it until terminal is true. It needs the scope that started the work and this key's current access, and reading it never resumes work stopped by a change in that access. A succeeded operation can still include items that failed, so read its item outcomes before retrying. A cancel finishes once the cancel is recorded, and a merge operation stays open as long as any sent merge is unresolved.

Requires an active connection. Access to existing work is checked against the connection that started it.

MCP action: `get_operation`. Its argument names match the fields below; an HTTP header is passed using its argument name in MCP.

## Parameters

| Name           | Send in | Required | Type or allowed values | Notes |
| -------------- | ------- | -------- | ---------------------- | ----- |
| `operation_id` | path    | Yes      | string                 |       |

## Response

| HTTP status | Result                                   |
| ----------- | ---------------------------------------- |
| `200`       | The current operation and safe controls. |

Required fields are required within their containing object. Notes identify fields that apply only to a particular response alternative.

| Response field                                                    | Type                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Required in object | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data`                                                            | OperationReceipt                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.id`                                                         | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.object`                                                     | `"operation"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.version`                                                    | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.resource_id`                                                | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.resource_type`                                              | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.status`                                                     | `"pending"`, `"succeeded"`, `"failed"`, `"canceled"`, `"needs_attention"`                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.terminal`                                                   | boolean                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.created_at`                                                 | string (date-time)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.ended_at`                                                   | string (date-time) or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.reason_code`                                                | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.replayed`                                                   | `true`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.operation_type`                                             | `"scan_cancel"`, `"ai_assessment"`, `"ai_assessment_cancel"`, `"review_update"`, `"exclusion_create"`, `"exclusion_update"`, `"scheduled_batch_create"`, `"scheduled_batch_update"`, `"scheduled_batch_cancel"`, `"scheduled_run_cancel"`, `"scheduled_record_cancel"`, `"schedule_create"`, `"schedule_update"`, `"webhook_endpoint_create"`, `"webhook_endpoint_update"`, `"webhook_secret_rotate"`, `"endpoint_verification"`, `"webhook_replay"`, `"merge_rebuild"`, `"scheduled_batch_transfer"`, `"webhook_endpoint_transfer"` | Yes                | When data.operation_type is `"scan_cancel"`, `"ai_assessment"`, `"ai_assessment_cancel"`, `"review_update"`, `"exclusion_create"`, `"exclusion_update"`, `"scheduled_batch_create"`, `"scheduled_batch_update"`, `"scheduled_batch_cancel"`, `"scheduled_run_cancel"`, `"scheduled_record_cancel"`, `"schedule_create"`, `"schedule_update"`, `"webhook_endpoint_create"`, `"webhook_endpoint_update"`, `"webhook_secret_rotate"`, `"endpoint_verification"`, `"webhook_replay"`, `"merge_rebuild"`, `"scheduled_batch_transfer"`, `"webhook_endpoint_transfer"`. |
| `data.action_metadata`                                            | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.action_metadata.resource_version`                           | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.action_metadata.allowed_actions`                            | array of string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes                |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `data.operation_type`                                             | `"merge_execute"`, `"merge_cancel"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Yes                | When data.operation_type is `"merge_execute"`, `"merge_cancel"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.execute_not_before`                         | string (date-time)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Yes                | When data.operation_type is `"merge_execute"`, `"merge_cancel"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_expires_at`                   | string (date-time)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Yes                | When data.operation_type is `"merge_execute"`, `"merge_cancel"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.operation_type`                                             | `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.plan_revision`                              | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.effects_digest`                             | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.preview_digest`                             | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.recovery_coverage_digest`                   | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement`                  | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement.scope`            | `"organization_baseline"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement.mode`             | `"api_key_allowed"`, `"not_allowed"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement.policy_version`   | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement.grant_evaluation` | `"at_execution"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_requirement.reason_code`      | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.action_metadata.authorization_state`                        | `"unauthorized"`, `"authorized"`, `"rejected"`, `"invalidated"`, `"expired"`                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Yes                | When data.operation_type is `"plan_prepare"`, `"plan_revision_prepare"`, `"retry_plan_prepare"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `data.operation_type`                                             | `"review_bulk_update"`, `"exclusion_bulk_create"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results`                                    | array of object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].index`                            | integer                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].outcome`                          | `"succeeded"`, `"failed"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].resource_ref`                     | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].resource_ref.id`                  | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].resource_ref.version`             | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].error`                            | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].error.code`                       | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].error.message`                    | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.action_metadata.results[].error.param`                      | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 | When data.operation_type is `"review_bulk_update"`, `"exclusion_bulk_create"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.operation_type`                                             | `"scan"`, `"scan_continue"`                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Yes                | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child`                                   | object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Yes                | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child.state`                             | `"not_requested"`, `"pending_admission"`, `"admitted"`, `"skipped"`, `"failed"`                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Yes                | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child.reason_code`                       | string or null                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | Yes                | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child.ai_run_id`                         | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child.ai_operation_id`                   | string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | No                 | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `data.action_metadata.ai_child.operation_url`                     | string (uri)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | No                 | When data.operation_type is `"scan"`, `"scan_continue"`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

## Errors

| HTTP status | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`       | One of: credential_in_url, invalid_parameter, unknown_parameter.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `401`       | One of: missing_credential, invalid_credential, credential_expired, credential_revoked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `402`       | One of: payment_overdue.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `403`       | One of: scope_required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `404`       | One of: not_found.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`       | One of: already_merging, api_merges_not_allowed, authorization_expiring, authorization_policy_changed, backup_coverage_required, change_in_portal, configuration_changed, consent_required, grant_changed, group_changed, idempotency_conflict, last_rule, merge_execution_disabled, merge_limit_reached, not_duplicates, plan_changed, preview_in_flight, protected_field_conflict, record_unreadable, recovery_not_available, retry_not_available, rule_id_taken, rule_too_broad, rules_in_use, scan_in_progress, schedule_exists, schedule_owned_by_portal, selection_held, setup_required, too_many_columns, version_conflict. |
| `410`       | One of: resource_expired.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `412`       | One of: version_conflict.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `413`       | One of: request_too_large.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `422`       | One of: batch_rejected, budget_exceeded, invalid_selection, merge_limit_exceeded, unsupported_field.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `423`       | One of: organization_reopening.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `428`       | One of: customer_agreement_required.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `429`       | One of: rate_limited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `503`       | One of: service_unavailable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

See [errors and recovery](https://neondeerdata.com/docs/api/errors/) and [safe retries](https://neondeerdata.com/docs/api/requests/) before repeating a write.

The [public OpenAPI document](https://neondeerdata.com/docs/api/meta/openapi/) lists generally available API families. Alpha operations may not appear in that document; their request and response fields are listed on this page. Use the [API Playground](https://neondeerdata.com/docs/api/testing/) to inspect a real response with your connection's access.