Operation status

The APIs on this page require alpha access for your organization. App availability and API access are separate. Check access and permissions.

Request

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 and safe retries before repeating a write.

The public OpenAPI document 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 to inspect a real response with your connection's access.