Create a table from selected rows

This page documents the canonical HTTP contract for this endpoint.

Non-explicit scopes require sourceTableId. filtered requires filters.filters; subset requires rowIds; firstN requires firstN. Explicit mode requires both explicitColumns and explicitRows and forbids a source table. Direct materialization is capped at 1,000 rows, 50 columns, and 50,000 cells; explicit transcription is capped at 100 rows and 50 columns. Larger supported materializations require exact resumable approval counts; hard maxima are 10,000 rows, 100 columns, and 500,000 cells. The returned operation envelope contains the execution receipt.

Body parameters

schema_version · optional
string
Literal command_center.research_table_materialization_plan.v1.
operationId · optional
string
Must be research_table.create_table_from_rows; default is this value.
summary · optional
string|null
Optional operation summary.
sourceTableId · optional
string|null
Required except explicit mode.
sourceTableName · optional
string|null
Optional display name for the source.
tableName · optional
string|null
Optional destination name.
scope · optional
string
filtered (default), all, subset, firstN, or explicit.
filters · optional
object|null
For filtered scope, must contain a nonempty filters member.
rowIds · optional
array<string>|null
Unique nonblank source row IDs for subset; maximum 10,000.
firstN · optional
integer|null
Required only for firstN; 1–10,000.
matchedCount · optional
integer|null
Optional bounded match count, 0–10,000.
includeColumns · optional
array<string>|null
Optional unique column keys, maximum 100.
excludeColumns · optional
array<string>|null
Optional unique column keys, maximum 100; cannot overlap includeColumns.
explicitColumns · optional
array<string>|null
Explicit mode only; maximum 50. Must pair with explicitRows.
explicitRows · optional
array<object>|null
Explicit mode only; maximum 100 rows and 50 columns.
ingestGeneration · optional
string
Generated by default; 8–80 chars matching the contract pattern.
largeJobApproval · optional
object|null
Required for oversized resumable jobs: approved:true, rowCount 1–10,000, columnCount 1–100, cellCount 1–500,000, resumable:true; counts must match plan.

Name	Type	Description
schema_version	string	Literal command_center.research_table_materialization_plan.v1.
operationId	string	Must be research_table.create_table_from_rows; default is this value.
summary	string\|null	Optional operation summary.
sourceTableId	string\|null	Required except explicit mode.
sourceTableName	string\|null	Optional display name for the source.
tableName	string\|null	Optional destination name.
scope	string	filtered (default), all, subset, firstN, or explicit.
filters	object\|null	For filtered scope, must contain a nonempty filters member.
rowIds	array<string>\|null	Unique nonblank source row IDs for subset; maximum 10,000.
firstN	integer\|null	Required only for firstN; 1–10,000.
matchedCount	integer\|null	Optional bounded match count, 0–10,000.
includeColumns	array<string>\|null	Optional unique column keys, maximum 100.
excludeColumns	array<string>\|null	Optional unique column keys, maximum 100; cannot overlap includeColumns.
explicitColumns	array<string>\|null	Explicit mode only; maximum 50. Must pair with explicitRows.
explicitRows	array<object>\|null	Explicit mode only; maximum 100 rows and 50 columns.
ingestGeneration	string	Generated by default; 8–80 chars matching the contract pattern.
largeJobApproval	object\|null	Required for oversized resumable jobs: approved:true, rowCount 1–10,000, columnCount 1–100, cellCount 1–500,000, resumable:true; counts must match plan.

Errors

Status	Meaning
401	Authentication is required.
403	The caller lacks access to the resource or the tables:read + tables:write scope.
422	The request does not satisfy the route or typed request contract.

Example

bash

curl -X POST "https://app.autotouch.ai/api/tables/materializations/from-rows" \
  -H "Authorization: Bearer $AUTOTOUCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "sourceTableId": "68d2c6a1a833d60619000001",
  "scope": "firstN",
  "firstN": 50,
  "includeColumns": ["company_name", "website"]
}'

Request body

json

{
  "sourceTableId": "68d2c6a1a833d60619000001",
  "scope": "firstN",
  "firstN": 50,
  "includeColumns": ["company_name", "website"]
}

Response example

json

{
  "status": "completed",
  "runId": "68d2c6a1a833d60619000002",
  "receipt": {"schemaVersion": "command_center.research_table_materialization_plan.run_receipt.v1", "runtime": "v3", "approvalKind": "mutate_table", "runId": "68d2c6a1a833d60619000002", "threadId": "thread-example", "previewId": null, "summary": "Create Snapshot from Target accounts", "operationId": "research_table.create_table_from_rows", "status": "completed", "sourceTableId": "68d2c6a1a833d60619000001", "sourceTableName": "Target accounts", "tableId": "68d2c6a1a833d60619000003", "tableName": "Snapshot", "tableUrl": "/research?tableId=68d2c6a1a833d60619000003", "matchedCount": 50, "rowsInserted": 50, "scope": "firstN", "filters": null, "ingestGeneration": "rtmat_example", "resumable": true, "pagesCompleted": 1, "createdAt": "2026-09-27T16:00:00+00:00"},
  "result": {"schemaVersion": "command_center.research_table_materialization_plan.run_receipt.v1", "runtime": "v3", "approvalKind": "mutate_table", "runId": "68d2c6a1a833d60619000002", "threadId": "thread-example", "previewId": null, "summary": "Create Snapshot from Target accounts", "operationId": "research_table.create_table_from_rows", "status": "completed", "sourceTableId": "68d2c6a1a833d60619000001", "sourceTableName": "Target accounts", "tableId": "68d2c6a1a833d60619000003", "tableName": "Snapshot", "tableUrl": "/research?tableId=68d2c6a1a833d60619000003", "matchedCount": 50, "rowsInserted": 50, "scope": "firstN", "filters": null, "ingestGeneration": "rtmat_example", "resumable": true, "pagesCompleted": 1, "createdAt": "2026-09-27T16:00:00+00:00"},
  "deepLink": "/research?tableId=68d2c6a1a833d60619000003",
  "replayed": false
}