Batches and ownership

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

List batches of scheduled runs

GET /v1/scheduled-runs/batches

Lists batches of scheduled runs, one page at a time. state can be sent more than once to match any of them.

Requires scheduled_runs:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: list_scheduled_run_batches. 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
limit	query	No	integer
cursor	query	No	string
target_id	query	No	string
object_type	query	No	string
integration_id	query	No	string
state	query	No	array of "pending", "in_progress", "ended"	Repeat this query parameter for multiple values.
created_at_from	query	No	string (date-time)
created_at_before	query	No	string (date-time)
fire_at_from	query	No	string (date-time)
fire_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", "fire_at", "-fire_at"

Response

HTTP status	Result
200	A page of batches.

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	"scheduled_run_batch"	Yes
data[].id	string	Yes
data[].version	string	Yes
data[].target_id	string	Yes
data[].workflow_version_id	string or null	Yes
data[].target_revision	string or null	Yes
data[].object_type	string	Yes
data[].fire_at	string (date-time)	Yes
data[].timezone	string	Yes
data[].state	"pending", "in_progress", "ended"	Yes
data[].record_count	integer	Yes
data[].run_counts	object	Yes
data[].run_counts.pending	integer	Yes
data[].run_counts.sending	integer	Yes
data[].run_counts.sent	integer	Yes
data[].run_counts.failed	integer	Yes
data[].run_counts.canceled	integer	Yes
data[].run_counts.skipped	integer	Yes
data[].run_counts.needs_attention	integer	Yes
data[].scheduled_by	object	Yes
data[].scheduled_by.kind	"integration"	Yes	When data[].scheduled_by.kind is "integration".
data[].scheduled_by.integration_id	string	Yes	When data[].scheduled_by.kind is "integration".
data[].scheduled_by.kind	"person"	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.workspace_member_id	string	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.name	string or null	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.kind	"workflow"	Yes	When data[].scheduled_by.kind is "workflow".
data[].created_at	string (date-time)	Yes
data[].ended_at	string (date-time) or null	Yes
data[].expires_at	string (date-time) 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, invalid_request, unknown_parameter, invalid_cursor.
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: authorization_policy_changed, batch_started, conflict, destination_unavailable, grant_changed, idempotency_conflict, setup_required, target_changed, version_conflict.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: budget_exceeded, invalid_fire_time, invalid_selection, target_version_unavailable, unsupported_ownership.
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.

Schedule a workflow for records

POST /v1/scheduled-runs/batches

Schedules a workflow to run once for each record you send, all at fire_at. This runs the workflow in Attio on those records. Read the workflows you can schedule first, then confirm the workflow, the records and the time with the person before you schedule anything. Send the workflow's id, version and workflow_version_id as you read them from the workflow; if the workflow changed since, the answer is target_changed and nothing is scheduled.

Requires scheduled_runs:create. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: create_scheduled_run_batch. 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
target_id	JSON body	Yes	string
expected_target_version	JSON body	Yes	string
workflow_version_id	JSON body	Yes	string
object_type	JSON body	Yes	string
record_ids	JSON body	Yes	array of string (uuid)
fire_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.
timezone	JSON body	Yes	string
client_reference	JSON body	No	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
201	The batch is scheduled. The receipt names it.

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, invalid_request, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	One of: scope_required, plan_required, not_available.
404	One of: not_found.
409	One of: idempotency_conflict, target_changed, grant_changed, setup_required.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: invalid_fire_time, invalid_selection, target_version_unavailable, budget_exceeded.
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.

Get a batch

GET /v1/scheduled-runs/batches/{batch_id}

Gets one batch of scheduled runs, with how many of its runs are in each state.

Requires scheduled_runs:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_scheduled_run_batch. 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
batch_id	path	Yes	string

Response

HTTP status	Result
200	The batch.

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	ScheduledRunBatch	Yes
data.object	"scheduled_run_batch"	Yes
data.id	string	Yes
data.version	string	Yes
data.target_id	string	Yes
data.workflow_version_id	string or null	Yes
data.target_revision	string or null	Yes
data.object_type	string	Yes
data.fire_at	string (date-time)	Yes
data.timezone	string	Yes
data.state	"pending", "in_progress", "ended"	Yes
data.record_count	integer	Yes
data.run_counts	object	Yes
data.run_counts.pending	integer	Yes
data.run_counts.sending	integer	Yes
data.run_counts.sent	integer	Yes
data.run_counts.failed	integer	Yes
data.run_counts.canceled	integer	Yes
data.run_counts.skipped	integer	Yes
data.run_counts.needs_attention	integer	Yes
data.scheduled_by	object	Yes
data.scheduled_by.kind	"integration"	Yes	When data.scheduled_by.kind is "integration".
data.scheduled_by.integration_id	string	Yes	When data.scheduled_by.kind is "integration".
data.scheduled_by.kind	"person"	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.workspace_member_id	string	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.name	string or null	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.kind	"workflow"	Yes	When data.scheduled_by.kind is "workflow".
data.created_at	string (date-time)	Yes
data.ended_at	string (date-time) or null	Yes
data.expires_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	One of: scope_required.
404	One of: not_found.
409	One of: authorization_policy_changed, batch_started, conflict, destination_unavailable, grant_changed, idempotency_conflict, setup_required, target_changed, version_conflict.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: budget_exceeded, invalid_fire_time, invalid_selection, target_version_unavailable, unsupported_ownership.
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.

Move a batch to a new time

PATCH /v1/scheduled-runs/batches/{batch_id}

Moves a batch of scheduled runs to a new time. Send the batch's version as expected_version. Works only before its first run starts; after that the answer is batch_started. What this replaces is not kept, so it can't be undone.

Requires scheduled_runs:update. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: reschedule_scheduled_run_batch. 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
batch_id	path	Yes	string
expected_version	JSON body	Yes	string
expected_target_version	JSON body	Yes	string
workflow_version_id	JSON body	Yes	string
fire_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.
timezone	JSON body	Yes	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The batch is moved.

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, invalid_request, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	One of: scope_required, plan_required, not_available.
404	One of: not_found.
409	One of: idempotency_conflict, version_conflict, target_changed, grant_changed, authorization_policy_changed, batch_started, setup_required.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: invalid_fire_time.
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.

List a batch's runs

GET /v1/scheduled-runs/batches/{batch_id}/runs

Lists one batch's runs, one page at a time. status can be sent more than once to match any of them.

Requires scheduled_runs:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: list_scheduled_run_batch_runs. 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
batch_id	path	Yes	string
limit	query	No	integer
cursor	query	No	string
status	query	No	array of "pending", "sending", "sent", "failed", "canceled", "skipped", "needs_attention"	Repeat this query parameter for multiple values.
record_id	query	No	string
sort	query	No	"fire_at", "-fire_at", "id", "-id"

Response

HTTP status	Result
200	A page of the batch's runs.

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 ScheduledRun	Yes
data[].object	"scheduled_run"	Yes
data[].id	string	Yes
data[].version	string	Yes
data[].batch_id	string	Yes
data[].target_id	string	Yes
data[].object_type	string	Yes
data[].record_id	string	Yes
data[].status	"pending", "sending", "sent", "failed", "canceled", "skipped", "needs_attention"	Yes
data[].delivery_outcome	"not_sent", "accepted", "rejected", "unknown"	Yes
data[].terminal	boolean	Yes
data[].reason	"canceled_by_member", "canceled_by_workflow", "canceled_by_integration", "disconnected", "workflow_off", "object_changed", "inputs_changed", "late", "rejected", "unreachable", "unsafe_destination", "target_changed", "authority_revoked" or null	Yes
data[].attempts	integer	Yes
data[].next_attempt_at	string (date-time) or null	Yes
data[].fire_at	string (date-time)	Yes
data[].timezone	string	Yes
data[].sent_at	string (date-time) or null	Yes
data[].ended_at	string (date-time) or null	Yes
data[].expires_at	string (date-time) or null	Yes
data[].scheduled_by	object	Yes
data[].scheduled_by.kind	"integration"	Yes	When data[].scheduled_by.kind is "integration".
data[].scheduled_by.integration_id	string	Yes	When data[].scheduled_by.kind is "integration".
data[].scheduled_by.kind	"person"	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.workspace_member_id	string	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.name	string or null	Yes	When data[].scheduled_by.kind is "person".
data[].scheduled_by.kind	"workflow"	Yes	When data[].scheduled_by.kind is "workflow".
data[].created_at	string (date-time)	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, invalid_request, unknown_parameter, invalid_cursor.
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: authorization_policy_changed, batch_started, conflict, destination_unavailable, grant_changed, idempotency_conflict, setup_required, target_changed, version_conflict.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: budget_exceeded, invalid_fire_time, invalid_selection, target_version_unavailable, unsupported_ownership.
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.

Cancel a batch's runs that have not started

POST /v1/scheduled-runs/batches/{batch_id}/cancel

Cancels a batch's runs that have not started. Send the batch's version as expected_version. Works only on runs this API key scheduled or was given, and needs no extra scope.

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

MCP action: cancel_scheduled_run_batch. 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
batch_id	path	Yes	string
expected_version	JSON body	Yes	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The cancel is accepted.

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, invalid_request, 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: idempotency_conflict, version_conflict.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: budget_exceeded, invalid_fire_time, invalid_selection, target_version_unavailable, unsupported_ownership.
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.

Get who owns a batch

GET /v1/scheduled-runs/batches/{batch_id}/ownership

Gets who scheduled a batch and, for a batch an API key scheduled, the API key that controls it now. Only the controlling key moves or cancels the batch. The controlling key, or a key with ownership permission and access to all of the workflow's history, can transfer it.

Requires scheduled_runs:read and scheduled_runs:config:read. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: get_scheduled_run_batch_ownership. 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
batch_id	path	Yes	string

Response

HTTP status	Result
200	The batch's ownership.

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	"scheduled_run_batch_ownership"	Yes
data.batch_id	string	Yes
data.version	string	Yes
data.scheduled_by	object	Yes
data.scheduled_by.kind	"integration"	Yes	When data.scheduled_by.kind is "integration".
data.scheduled_by.integration_id	string	Yes	When data.scheduled_by.kind is "integration".
data.scheduled_by.kind	"person"	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.workspace_member_id	string	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.name	string or null	Yes	When data.scheduled_by.kind is "person".
data.scheduled_by.kind	"workflow"	Yes	When data.scheduled_by.kind is "workflow".
data.controlling_integration_id	string 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	One of: scope_required.
404	One of: not_found.
409	One of: authorization_policy_changed, batch_started, conflict, destination_unavailable, grant_changed, idempotency_conflict, setup_required, target_changed, version_conflict.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: budget_exceeded, invalid_fire_time, invalid_selection, target_version_unavailable, unsupported_ownership.
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.

Give a batch to another API key

POST /v1/scheduled-runs/batches/{batch_id}/ownership-transfers

Gives control of a batch that hasn't started to another API key of your organization. Send the batch's version as expected_version and its workflow's version as expected_target_version. The other key must already be able to schedule this workflow at the version the batch uses; this key keeps no control of the batch unless it has ownership permission and access to all of the workflow's history.

Requires scheduled_runs:ownership:write. The connection also needs access to the relevant tables, objects, or workflows.

MCP action: transfer_scheduled_run_batch. 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
batch_id	path	Yes	string
destination_integration_id	JSON body	Yes	string
expected_version	JSON body	Yes	string
expected_target_version	JSON body	Yes	string
request_key	Header: Idempotency-Key	Yes	string

Response

HTTP status	Result
200	The batch's control moved.

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, invalid_request, unknown_parameter.
401	One of: missing_credential, invalid_credential, credential_expired, credential_revoked.
402	One of: payment_overdue.
403	One of: scope_required, plan_required, not_available.
404	One of: not_found.
409	One of: idempotency_conflict, version_conflict, target_changed, batch_started, destination_unavailable.
410	One of: resource_expired.
413	One of: request_too_large.
422	One of: unsupported_ownership.
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.