Estimate Sync to Table rows

This page documents the canonical HTTP contract for this endpoint.

This endpoint validates access to the source table and returns a count for the supplied draft config. It honors runScope, including selected IDs, filters, sorting, firstN, and processed/skipped options. Route conditions and Sync-to-Table readiness apply only within those candidate rows, including when routes are absent, unconditional, or use simple emptiness conditions. A route condition can reduce the selected count; it does not select replacement rows beyond the requested scope. The result counts eligible source rows, not destination rows or expanded list items, and is a snapshot that can change before execution. It is a read/estimate helper: it does not create a sync column, enqueue a run, write destination rows, or charge credits. For execution, use the approved Sync-to-Table workflow and its durable run lifecycle.

The registered research_table.sync_to_table operation explicitly declares this HTTP endpoint as its runtime estimate. Its related inspect_sync_to_table_sources dynamic read is a separate supporting tool; that tool name does not itself bind this endpoint. For list mode, inspect source columns first and use the returned source column ID, list path, and item keys. The example is illustrative; use distinct accessible source and destination table IDs and current column keys.

Path parameters

table_idrequired
string
Accessible source Research Table ID.

Name	Type	Description
table_idrequired	string	Accessible source Research Table ID.

Body parameters

config · optional
object
Draft Sync-to-Table provider configuration. Use a routes array; each route specifies a destination, syncMode (row, list, or entity), optional syncBehavior (link or copy; defaults to link), and explicit columnMappings. For list mode, include listSourceColumnId and listPath. Entity mode also uses identityMappings. See the registered research_table.sync_to_table operation contract.
runScoperequired
RunRequest
Candidate row scope. Requires scope: all, subset, row, firstN, or filtered. The estimator resolves this scope before applying route conditions and provider readiness.

Name	Type	Description
config	object	Draft Sync-to-Table provider configuration. Use a routes array; each route specifies a destination, syncMode (row, list, or entity), optional syncBehavior (link or copy; defaults to link), and explicit columnMappings. For list mode, include listSourceColumnId and listPath. Entity mode also uses identityMappings. See the registered research_table.sync_to_table operation contract.
runScoperequired	RunRequest	Candidate row scope. Requires scope: all, subset, row, firstN, or filtered. The estimator resolves this scope before applying route conditions and provider readiness.

Definitions

RunRequest

Run scope used to select candidate source rows. The estimate does not execute the configured sync.

Fields

scoperequired
string
One of all, subset, row, firstN, filtered.
rowIds · optional
array<string>
Required and unique valid row ObjectIds for subset; exactly one for row; unsupported with other scopes.
firstN · optional
integer
Positive integer required for firstN; also supported as a cap for filtered scope. Unsupported with all, subset, or row scope.
filters · optional
object
Required non-empty Research Table filter object for filtered scope; not a CRM FilterDescriptor.
unprocessedOnly · optional
boolean
When omitted, estimate defaults to unprocessedOnly=true.
skippedOnly · optional
boolean
Optional strict boolean to restrict scope to skipped rows.
maxAdmittedRows · optional
integer
Optional positive strict integer row cap.
sort · optional
object
Optional {column, direction}; direction is asc or desc. Sorting is not supported for subset/row scopes.

Name	Type	Description
scoperequired	string	One of all, subset, row, firstN, filtered.
rowIds	array<string>	Required and unique valid row ObjectIds for subset; exactly one for row; unsupported with other scopes.
firstN	integer	Positive integer required for firstN; also supported as a cap for filtered scope. Unsupported with all, subset, or row scope.
filters	object	Required non-empty Research Table filter object for filtered scope; not a CRM FilterDescriptor.
unprocessedOnly	boolean	When omitted, estimate defaults to unprocessedOnly=true.
skippedOnly	boolean	Optional strict boolean to restrict scope to skipped rows.
maxAdmittedRows	integer	Optional positive strict integer row cap.
sort	object	Optional {column, direction}; direction is asc or desc. Sorting is not supported for subset/row scopes.

SyncToTableRoute

The registered operation contract describes routes[] as the canonical config shape.

Fields

destinationTableId · optional
string
Existing destination table ID, unless destinationTableCreate is used.
syncModerequired
string
row, list, or entity.
syncBehavior · optional
string
link or copy.
listSourceColumnId · optional
string
Required in list mode; use the exact source column ID.
listPath · optional
string
Path to the array inside the list source JSON.
columnMappingsrequired
array<ColumnMapping>
Explicit row/item/literal mappings.
identityMappings · optional
array<object>
Required for entity mode; map identity fields and match strategy.

Name	Type	Description
destinationTableId	string	Existing destination table ID, unless destinationTableCreate is used.
syncModerequired	string	row, list, or entity.
syncBehavior	string	link or copy.
listSourceColumnId	string	Required in list mode; use the exact source column ID.
listPath	string	Path to the array inside the list source JSON.
columnMappingsrequired	array<ColumnMapping>	Explicit row/item/literal mappings.
identityMappings	array<object>	Required for entity mode; map identity fields and match strategy.

ColumnMapping

Use the mapping shape that matches the source scope.

Fields

sourceScoperequired
string
row, item, or literal.
sourceKey · optional
string
Source column key for row scope; may use sourceColumnId instead.
sourceColumnId · optional
string
Optional source column ID for row scope.
itemKey · optional
string
List-item field key returned by source inspection; use for item scope.
value · optional
any
Fixed value for literal scope.
destKeyrequired
string
Destination column key.
path · optional
string
Optional nested JSON path for a row-scope source.

Name	Type	Description
sourceScoperequired	string	row, item, or literal.
sourceKey	string	Source column key for row scope; may use sourceColumnId instead.
sourceColumnId	string	Optional source column ID for row scope.
itemKey	string	List-item field key returned by source inspection; use for item scope.
value	any	Fixed value for literal scope.
destKeyrequired	string	Destination column key.
path	string	Optional nested JSON path for a row-scope source.

Errors

Status	Meaning
401	Authentication is missing or invalid.
403	The caller lacks tables:write or cannot access the source table.
422	The run scope or request body failed model validation.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/67bd8c39c7d3e80f0a95b560/rows/sync-to-table/estimate" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
    -d '{
    "config": {
      "provider": "sync_to_table",
      "routes": [{
        "destinationTableId": "67bd8c39c7d3e80f0a95b561",
        "syncMode": "row",
        "syncBehavior": "link",
        "columnMappings": [{"sourceScope":"row","sourceKey":"domain","destKey":"domain"}]
      }]
    },
    "runScope": {"scope":"all"}
  }'

Request body

json

{
  "config": {
    "provider": "sync_to_table",
    "routes": [
      {
        "destinationTableId": "67bd8c39c7d3e80f0a95b561",
        "syncMode": "row",
        "syncBehavior": "link",
        "columnMappings": [
          { "sourceScope": "row", "sourceKey": "domain", "destKey": "domain" }
        ]
      }
    ]
  },
  "runScope": {
    "scope": "all"
  }
}

Response example

json

{
  "count": 42
}