fix(api): make async table imports observable, not just startable

`POST /import-async` pointed callers at `GET /api/v2/tables/jobs` to track
progress, but that endpoint filters to `type = 'export'` — imports are
derived onto the table itself, one write job at a time, and exports get a
separate list precisely because they are excluded from that derivation.
The public Table shape omitted those derived fields, so an async import
could be started and cancelled but never observed to completion, failure,
or progress. That is the gap the import/export/job-control set was meant
to close.

Table now carries `job` — id, type, status, rowsProcessed, error, or null
when idle — and the import-async docs point at the table rather than the
export list.

Author: TheodoreSpeaks

apps/docs/openapi-v2-tables.json

@@ -103,7 +103,8 @@
                         "insertLocked": false,
                         "updateLocked": false,
                         "deleteLocked": false
-                      }
+                      },
+                      "job": null
                     }
                   ],
                   "nextCursor": null
@@ -211,7 +212,8 @@
                         "insertLocked": false,
                         "updateLocked": false,
                         "deleteLocked": false
-                      }
+                      },
+                      "job": null
                     }
                   }
                 }
@@ -467,7 +469,8 @@
                         "deleteLocked": true
                       },
                       "createdAt": "2026-01-15T10:30:00.000Z",
-                      "updatedAt": "2026-01-16T09:12:00.000Z"
+                      "updatedAt": "2026-01-16T09:12:00.000Z",
+                      "job": null
                     }
                   }
                 }
@@ -1720,7 +1723,8 @@
                         "deleteLocked": true
                       },
                       "createdAt": "2026-01-15T10:30:00.000Z",
-                      "updatedAt": "2026-01-16T09:12:00.000Z"
+                      "updatedAt": "2026-01-16T09:12:00.000Z",
+                      "job": null
                     }
                   }
                 }
@@ -2916,7 +2920,7 @@
       "post": {
         "operationId": "importTableCsvAsync",
         "summary": "Import CSV (Background)",
-        "description": "Start a background import of a file already uploaded to workspace storage \u2014 the path for files too large for the synchronous import.\n\nReturns as soon as the job is queued. Track it with `GET /api/v2/tables/jobs` and stop it with `POST /job/cancel`. `fileKey` must sit under this workspace\u2019s storage prefix. The table\u2019s lock flags are checked before the job slot is claimed, so a locked table answers 423 here rather than failing inside the worker.",
+        "description": "Start a background import of a file already uploaded to workspace storage \u2014 the path for files too large for the synchronous import.\n\nReturns as soon as the job is queued. Track it on the table itself \u2014 `GET /api/v2/tables/{tableId}` returns a `job` object with `status`, `rowsProcessed` and `error` while the import runs \u2014 and stop it with `POST /job/cancel`. (`GET /api/v2/tables/jobs` lists exports only: those run concurrently and are not derived onto the table.) `fileKey` must sit under this workspace\u2019s storage prefix. The table\u2019s lock flags are checked before the job slot is claimed, so a locked table answers 423 here rather than failing inside the worker.",
         "tags": ["Tables"],
         "x-codeSamples": [
           {
@@ -3711,7 +3715,8 @@
           "folderId",
           "locks",
           "createdAt",
-          "updatedAt"
+          "updatedAt",
+          "job"
         ],
         "properties": {
           "id": {
@@ -3767,6 +3772,17 @@
           },
           "locks": {
             "$ref": "#/components/schemas/TableLocks"
+          },
+          "job": {
+            "oneOf": [
+              {
+                "$ref": "#/components/schemas/TableJobState"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "description": "In-flight background job, or null when the table is idle."
           }
         }
       },
@@ -5422,6 +5438,33 @@
             }
           }
         }
+      },
+      "TableJobState": {
+        "type": "object",
+        "description": "The table's in-flight background job. Import and delete jobs are derived onto the table itself (one write job per table), so the table is their status endpoint \u2014 poll `GET /api/v2/tables/{tableId}` after starting one. Exports are read-only and run concurrently, so they are listed separately by `GET /api/v2/tables/jobs` instead.",
+        "required": ["id", "type", "status", "rowsProcessed", "error"],
+        "properties": {
+          "id": {
+            "type": ["string", "null"],
+            "description": "Job id \u2014 pass to `POST /job/cancel` to stop it."
+          },
+          "type": {
+            "enum": ["import", "delete", "export", "backfill", "update", null],
+            "description": "Which kind of job is running."
+          },
+          "status": {
+            "enum": ["running", "ready", "failed", "canceled"],
+            "description": "`running` is in-flight; the rest are terminal."
+          },
+          "rowsProcessed": {
+            "type": "integer",
+            "description": "Rows handled so far \u2014 progress for a running job."
+          },
+          "error": {
+            "type": ["string", "null"],
+            "description": "Failure reason for a `failed` job; null otherwise."
+          }
+        }
       }
     },
     "responses": {

apps/sim/app/api/v2/tables/[tableId]/restore/route.test.ts

@@ -109,6 +109,7 @@ describe('POST /api/v2/tables/[tableId]/restore', () => {
         maxRows: 1000,
         folderId: null,
         locks: UNLOCKED,
+        job: null,
         createdAt: '2026-01-01T00:00:00.000Z',
         updatedAt: '2026-01-02T00:00:00.000Z',
       },

apps/sim/app/api/v2/tables/[tableId]/route.test.ts

@@ -192,6 +192,7 @@ describe('PATCH /api/v2/tables/[tableId]', () => {
         maxRows: 1000,
         folderId: null,
         locks: UNLOCKED,
+        job: null,
         createdAt: '2026-01-01T00:00:00.000Z',
         updatedAt: '2026-01-02T00:00:00.000Z',
       },
@@ -203,6 +204,31 @@ describe('PATCH /api/v2/tables/[tableId]', () => {
     expect(mockPerformUpdateTableLocks).not.toHaveBeenCalled()
   })
 
+  it('surfaces a running import so an async job is observable, not just startable', async () => {
+    // `POST /import-async` and `POST /job/cancel` let a caller start and stop an
+    // import; without this the table never reports that it is running, so there
+    // is nothing to poll between the two.
+    mockGetTableById.mockResolvedValue({
+      ...UPDATED_TABLE,
+      jobStatus: 'running',
+      jobId: 'job-1',
+      jobType: 'import',
+      jobRowsProcessed: 250,
+      jobError: null,
+    })
+    mockPerformRenameTable.mockResolvedValue({ success: true })
+
+    const res = await callPatch({ workspaceId: 'ws-1', name: 'Renamed' })
+
+    expect((await res.json()).data.table.job).toEqual({
+      id: 'job-1',
+      type: 'import',
+      status: 'running',
+      rowsProcessed: 250,
+      error: null,
+    })
+  })
+
   it('moves the table only after confirming the folder belongs to the workspace', async () => {
     mockPerformMoveTableToFolder.mockResolvedValue({ success: true })
 

apps/sim/app/api/v2/tables/import-csv/route.test.ts

@@ -121,6 +121,7 @@ describe('POST /api/v2/tables/import-csv', () => {
         maxRows: 1000,
         folderId: null,
         locks: UNLOCKED,
+        job: null,
         createdAt: '2026-01-01T00:00:00.000Z',
         updatedAt: '2026-01-01T00:00:00.000Z',
       },

apps/sim/app/api/v2/tables/utils.ts

@@ -65,6 +65,18 @@ export function toApiTable(table: TableDefinition) {
     maxRows: table.maxRows,
     folderId: table.folderId ?? null,
     locks: table.locks,
+    // `jobStatus` is the presence signal — the service leaves the whole group
+    // null when the table is idle. Without this an async import could be
+    // started and cancelled but never observed to completion or failure.
+    job: table.jobStatus
+      ? {
+          id: table.jobId ?? null,
+          type: table.jobType ?? null,
+          status: table.jobStatus,
+          rowsProcessed: table.jobRowsProcessed ?? 0,
+          error: table.jobError ?? null,
+        }
+      : null,
     createdAt: toIso(table.createdAt),
     updatedAt: toIso(table.updatedAt),
   }

apps/sim/lib/api/contracts/v2/tables.ts

@@ -76,6 +76,24 @@ export const V2_MAX_ROW_LIMIT = 1000
  * Public table shape emitted by `toApiTable` (timestamps ISO-serialized).
  * Concrete so the v2 contract describes exactly what the wire carries.
  */
+/**
+ * The table's current background job, or `null` when idle.
+ *
+ * This is how an async import or delete is observed. Those jobs are derived
+ * onto the table itself (one write job per table at a time), so the table is
+ * their status endpoint — unlike exports, which are read-only, run concurrently,
+ * and therefore have the dedicated `GET /api/v2/tables/jobs` list instead.
+ */
+export const v2TableJobStateSchema = z.object({
+  id: z.string().nullable(),
+  type: z.enum(['import', 'delete', 'export', 'backfill', 'update']).nullable(),
+  status: z.enum(['running', 'ready', 'failed', 'canceled']),
+  rowsProcessed: z.number(),
+  /** Failure reason for a `failed` job; `null` otherwise. */
+  error: z.string().nullable(),
+})
+export type V2TableJobState = z.output<typeof v2TableJobStateSchema>
+
 export const v2ApiTableSchema = z.object({
   id: z.string(),
   name: z.string(),
@@ -87,6 +105,8 @@ export const v2ApiTableSchema = z.object({
   folderId: z.string().nullable(),
   /** Governance flags. Writable only by a workspace admin via `PATCH`. */
   locks: tableLocksSchema,
+  /** In-flight background job, or `null` when the table is idle. */
+  job: v2TableJobStateSchema.nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
 })