# AI assessments Source: https://neondeerdata.com/docs/api/duplicate-detection/ai-assessments/ Request AI assessments and inspect the outcome for each duplicate set. 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/). ## List AI assessments ```http GET /v1/deduplication/ai-assessment-runs ``` Lists AI assessments, one page at a time. Requires `dedupe:read`. The connection also needs access to the relevant tables, objects, or workflows. MCP action: `list_dedupe_ai_assessments`. 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 | | ------------------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `object_type` | query | No | `"companies"`, `"people"` | | | `status` | query | No | array of `"queued"`, `"preparing"`, `"running"`, `"waiting"`, `"cancel_requested"`, `"needs_attention"`, `"completed"`, `"partial"`, `"failed"`, `"canceled"`, `"expired"` | Repeat this query parameter for multiple values. | | `parent_run_id` | query | No | string | | | `created_at_from` | query | No | string (date-time) | | | `created_at_before` | query | No | string (date-time) | | | `ended_at_from` | query | No | string (date-time) | | | `ended_at_before` | query | No | string (date-time) | | | `sort` | query | No | `"-created_at"`, `"created_at"` | | | `limit` | query | No | integer | | | `cursor` | query | No | string | | ### Response | HTTP status | Result | | ----------- | --------------------------------------------------------------------- | | `200` | The requested result. Asynchronous work returns an operation to poll. | 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` | array of object | Yes | | | `data[].object` | `"deduplication_ai_assessment_run"` | Yes | | | `data[].id` | string | Yes | | | `data[].version` | string | Yes | | | `data[].object_type` | `"companies"`, `"people"` | Yes | | | `data[].connection_id` | string | Yes | | | `data[].selection` | object | Yes | | | `data[].selection.type` | `"sets"` | Yes | When data\[\].selection.type is `"sets"`. | | `data[].selection.type` | `"scan_run"` | Yes | When data\[\].selection.type is `"scan_run"`. | | `data[].selection.run_id` | string | Yes | When data\[\].selection.type is `"scan_run"`. | | `data[].selection.type` | `"after_scan"` | Yes | When data\[\].selection.type is `"after_scan"`. | | `data[].parent_run_id` | string or null | Yes | | | `data[].status` | `"queued"`, `"preparing"`, `"running"`, `"waiting"`, `"cancel_requested"`, `"needs_attention"`, `"completed"`, `"partial"`, `"failed"`, `"canceled"`, `"expired"` | Yes | | | `data[].reason_code` | `"stopped_early"`, `"plan_allowance"`, `"budget_limited"`, `"stale_selection"`, `"canceled_by_request"`, `"expired"`, `"access_ended"`, `"evidence_not_authorized"`, `"consent_revoked"`, `"disconnected"`, `"provider_unreachable"`, `"provider_error"`, `"service_interrupted"`, `"operator_resolved"`, `"failed"` or null | Yes | | | `data[].budget` | object | Yes | | | `data[].budget.max_assessment_units` | integer | Yes | | | `data[].budget.consumed_units` | integer | Yes | | | `data[].expires_at` | string (date-time) | Yes | | | `data[].created_at` | string (date-time) | Yes | | | `data[].ended_at` | string (date-time) or null | Yes | | | `data[].client_reference` | string or null | Yes | | | `pagination` | object | Yes | | | `pagination.next_cursor` | string or null | Yes | | ### Errors | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor. | | `401` | One of: missing_credential, invalid_credential, credential_expired, credential_revoked. | | `402` | One of: payment_overdue. | | `403` | The current permissions, plan or policy do not allow this request. | | `404` | One of: not_found. | | `409` | The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. | | `410` | The requested resource or retained recovery data has expired. | | `412` | One of: version_conflict. | | `413` | One of: request_too_large. | | `422` | A field, filter or selection cannot be used for this request. | | `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. ## Start AI assessment ```http POST /v1/deduplication/ai-assessment-runs ``` Starts an AI assessment of chosen duplicate sets, or of a scan's results, within the unit budget and deadline you set. The sets are fixed when it starts and it runs in the background: poll the returned operation, then read the results. Choose a future deadline; the work also stops if this key loses access to the object. An assessment never starts or allows a merge. Requires `dedupe:ai:assess`. The connection also needs access to the relevant tables, objects, or workflows. MCP action: `start_dedupe_ai_assessment`. 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 | | ----------------------------------- | ------------------------- | ------------------ | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `connection_id` | JSON body | Yes | string | | | `object_type` | JSON body | Yes | `"companies"`, `"people"` | | | `selection` | JSON body | Yes | object | | | `selection.type` | Within the JSON value | Within this object | `"sets"` | When selection.type is `"sets"`. | | `selection.sets` | Within the JSON value | Within this object | array of object | When selection.type is `"sets"`. | | `selection.sets[].set_id` | Within the JSON value | Within this object | string | When selection.type is `"sets"`. | | `selection.sets[].expected_version` | Within the JSON value | Within this object | string | When selection.type is `"sets"`. | | `selection.type` | Within the JSON value | Within this object | `"scan_run"` | When selection.type is `"scan_run"`. | | `selection.run_id` | Within the JSON value | Within this object | string | When selection.type is `"scan_run"`. | | `selection.expected_version` | Within the JSON value | Within this object | string | When selection.type is `"scan_run"`. | | `budget` | JSON body | Yes | object | | | `budget.max_assessment_units` | Within the JSON value | Within this object | integer | | | `expires_at` | JSON body | Yes | string (date-time) | An RFC 3339 time in UTC ending in Z, for example 2026-11-04T18:30:00Z. A fraction of a second is rounded up to the next whole second. | | `client_reference` | JSON body | No | string | | | `request_key` | Header: `Idempotency-Key` | Yes | string | | ### Response | HTTP status | Result | | ----------- | --------------------------------------------------------------------- | | `202` | The requested result. Asynchronous work returns an operation to poll. | 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` | object | 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"`. | Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See [operation status](https://neondeerdata.com/docs/api/operations/). ### Errors | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request. | | `401` | One of: missing_credential, invalid_credential, credential_expired, credential_revoked. | | `402` | One of: payment_overdue. | | `403` | The current permissions, plan or policy do not allow this request. | | `404` | One of: not_found. | | `409` | The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. | | `410` | The requested resource or retained recovery data has expired. | | `412` | One of: version_conflict. | | `413` | One of: request_too_large. | | `422` | A field, filter or selection cannot be used for this request. | | `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. ## Get AI assessment ```http GET /v1/deduplication/ai-assessment-runs/{ai_run_id} ``` Gets one AI assessment and its progress. Requires `dedupe:read`. The connection also needs access to the relevant tables, objects, or workflows. MCP action: `get_dedupe_ai_assessment`. 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 | | ----------- | ------- | -------- | ---------------------- | ----- | | `ai_run_id` | path | Yes | string | | ### Response | HTTP status | Result | | ----------- | --------------------------------------------------------------------- | | `200` | The requested result. Asynchronous work returns an operation to poll. | 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` | object | Yes | | | `data.object` | `"deduplication_ai_assessment_run"` | Yes | | | `data.id` | string | Yes | | | `data.version` | string | Yes | | | `data.object_type` | `"companies"`, `"people"` | Yes | | | `data.connection_id` | string | Yes | | | `data.selection` | object | Yes | | | `data.selection.type` | `"sets"` | Yes | When data.selection.type is `"sets"`. | | `data.selection.type` | `"scan_run"` | Yes | When data.selection.type is `"scan_run"`. | | `data.selection.run_id` | string | Yes | When data.selection.type is `"scan_run"`. | | `data.selection.type` | `"after_scan"` | Yes | When data.selection.type is `"after_scan"`. | | `data.parent_run_id` | string or null | Yes | | | `data.status` | `"queued"`, `"preparing"`, `"running"`, `"waiting"`, `"cancel_requested"`, `"needs_attention"`, `"completed"`, `"partial"`, `"failed"`, `"canceled"`, `"expired"` | Yes | | | `data.reason_code` | `"stopped_early"`, `"plan_allowance"`, `"budget_limited"`, `"stale_selection"`, `"canceled_by_request"`, `"expired"`, `"access_ended"`, `"evidence_not_authorized"`, `"consent_revoked"`, `"disconnected"`, `"provider_unreachable"`, `"provider_error"`, `"service_interrupted"`, `"operator_resolved"`, `"failed"` or null | Yes | | | `data.budget` | object | Yes | | | `data.budget.max_assessment_units` | integer | Yes | | | `data.budget.consumed_units` | integer | Yes | | | `data.expires_at` | string (date-time) | Yes | | | `data.created_at` | string (date-time) | Yes | | | `data.ended_at` | string (date-time) or null | Yes | | | `data.client_reference` | string or null | Yes | | ### 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` | The current permissions, plan or policy do not allow this request. | | `404` | One of: not_found. | | `409` | The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. | | `410` | The requested resource or retained recovery data has expired. | | `412` | One of: version_conflict. | | `413` | One of: request_too_large. | | `422` | A field, filter or selection cannot be used for this request. | | `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. ## Get AI results ```http GET /v1/deduplication/ai-assessment-runs/{ai_run_id}/items ``` Lists the results of an AI assessment, one page at a time. Requires `dedupe:read`. The connection also needs access to the relevant tables, objects, or workflows. MCP action: `list_dedupe_ai_assessment_results`. 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 | | ----------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ | | `ai_run_id` | path | Yes | string | | | `set_id` | query | No | string | | | `outcome` | query | No | array of `"scored"`, `"insufficient_evidence"`, `"excluded"`, `"source_unavailable"`, `"stale_selection"`, `"budget_limited"`, `"canceled"`, `"failed"` | Repeat this query parameter for multiple values. | | `limit` | query | No | integer | | | `cursor` | query | No | string | | ### Response | HTTP status | Result | | ----------- | --------------------------------------------------------------------- | | `200` | The requested result. Asynchronous work returns an operation to poll. | 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` | array of object | Yes | | | `data[].set_id` | string | Yes | | | `data[].set_version` | string | Yes | | | `data[].outcome` | `"scored"`, `"insufficient_evidence"`, `"excluded"`, `"source_unavailable"`, `"stale_selection"`, `"budget_limited"`, `"canceled"`, `"failed"` or null | Yes | | | `data[].publication` | `"current"`, `"previous"`, `"unpublished"` | Yes | | | `data[].coverage` | object | Yes | | | `data[].coverage.root` | `"complete"`, `"empty"`, `"capped"`, `"omitted"`, `"unreadable"`, `"unknown"` | Yes | | | `data[].coverage.related` | `"complete"`, `"empty"`, `"capped"`, `"omitted"`, `"unreadable"`, `"unknown"` | Yes | | | `data[].pairs` | array of object | No | | | `data[].pairs[].record_id` | string | Yes | | | `data[].pairs[].ai_score` | integer or null | Yes | | | `data[].pairs[].origin` | `"cached"`, `"newly_assessed"` | Yes | | | `data[].pairs[].scored_at` | string (date-time) or null | Yes | | | `data[].pairs[].input_read_at` | string (date-time) or null | Yes | | | `data[].pairs[].last_checked_at` | string (date-time) or null | Yes | | | `data[].pairs[].evidence_expires_at` | string (date-time) or null | Yes | | | `pagination` | object | Yes | | | `pagination.next_cursor` | string or null | Yes | | | `references` | array of object | Yes | | | `references[].provider` | `"attio"` | Yes | | | `references[].workspace_id` | string or null | Yes | | | `references[].object_id` | string or null | Yes | | | `references[].object_slug` | string or null | Yes | | | `references[].records` | array of object | Yes | | | `references[].records[].record_id` | string | Yes | | | `references[].records[].web_url` | string (uri) or null | Yes | | | `references[].records[].attributes` | array of object | Yes | | | `references[].records[].attributes[].attribute_id` | string or null | Yes | | | `references[].records[].attributes[].attribute_slug` | string or null | Yes | | | `references[].records[].via` | array of object | Yes | | | `references[].records[].via[].source_object_id` | string or null | Yes | | | `references[].records[].via[].source_object_slug` | string or null | Yes | | | `references[].records[].via[].source_record_id` | string | Yes | | | `references[].records[].via[].attribute_id` | string or null | Yes | | | `references[].records[].via[].attribute_slug` | string or null | Yes | | | `references[].records[].via[].target_object_id` | string or null | Yes | | | `references[].records[].via[].target_object_slug` | string or null | Yes | | | `references[].records[].via[].target_record_id` | string | Yes | | | `references[].lookup_hint` | object | Yes | | | `references[].lookup_hint.resource` | `"records"` | Yes | | | `references[].lookup_hint.object` | string | Yes | | | `references[].lookup_hint.record_ids` | array of string | Yes | | ### Errors | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request, invalid_cursor. | | `401` | One of: missing_credential, invalid_credential, credential_expired, credential_revoked. | | `402` | One of: payment_overdue. | | `403` | The current permissions, plan or policy do not allow this request. | | `404` | One of: not_found. | | `409` | The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. | | `410` | The requested resource or retained recovery data has expired. | | `412` | One of: version_conflict. | | `413` | One of: request_too_large. | | `422` | A field, filter or selection cannot be used for this request. | | `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. ## Cancel AI assessment ```http POST /v1/deduplication/ai-assessment-runs/{ai_run_id}/cancel ``` Stops an unfinished AI assessment this key started. Send the assessment's version as expected_version. Needs no extra scope, but the key must still have access to the object. Requires an active connection. Access to existing work is checked against the connection that started it. MCP action: `cancel_dedupe_ai_assessment`. 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 | | ------------------ | ------------------------- | -------- | ---------------------- | ----- | | `ai_run_id` | path | Yes | string | | | `expected_version` | JSON body | Yes | string | | | `request_key` | Header: `Idempotency-Key` | Yes | string | | ### Response | HTTP status | Result | | ----------- | --------------------------------------------------------------------- | | `202` | The requested result. Asynchronous work returns an operation to poll. | 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` | object | 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"`. | Accepted work can continue after the request returns. Follow its returned status or operation until it finishes; accepting work does not mean every item succeeded. See [operation status](https://neondeerdata.com/docs/api/operations/). ### Errors | HTTP status | Meaning | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | One of: credential_in_url, invalid_parameter, unknown_parameter, invalid_request. | | `401` | One of: missing_credential, invalid_credential, credential_expired, credential_revoked. | | `402` | One of: payment_overdue. | | `403` | The current permissions, plan or policy do not allow this request. | | `404` | One of: not_found. | | `409` | The request conflicts with current resource state, authorization or an earlier request. Read the error code and current resource before retrying. | | `410` | The requested resource or retained recovery data has expired. | | `412` | One of: version_conflict. | | `413` | One of: request_too_large. | | `422` | A field, filter or selection cannot be used for this request. | | `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.