Skip to content
Try for free
On this page

Tables

Get table import

Get an import's progress and status. During `uploading`, the signed upload token is required; omitting it returns `404`. OAuth scope: `api:read`.

GET/api/v2/tables/imports/{importId}

Get an import's progress and status. During uploading, the signed upload token is required; omitting it returns 404.

OAuth scope: api:read.

Authentication

Send a personal or workspace API key in X-API-Key. See key types and access; operations that reject workspace keys say so in their description.

Send X-API-Key in the request header.

Alternatively

Send a Sim OAuth access token in Authorization: Bearer. See OAuth authentication and scopes.

Authorization: Bearer YOUR_ACCESS_TOKEN

Required scopes: api:read

OAuth flows
json
{
  "authorizationCode": {
    "authorizationUrl": "https://www.sim.ai/api/auth/oauth2/authorize",
    "tokenUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "refreshUrl": "https://www.sim.ai/api/auth/oauth2/token",
    "scopes": {
      "api:read": "Read your workspaces, workflows, files, tables, and logs",
      "api:write": "Read, create, change, run, and delete resources in your workspaces",
      "offline_access": "Stay signed in without asking again"
    }
  }
}

OAuth scope: api:read.

Path parameters

importIdstringRequired

Unique table-import identifier.

minLength
1

Query parameters

workspaceIdstringRequired

Workspace that owns the transfer resource.

minLength
1
maxLength
128

Header parameters

upload-tokenstring

Signed upload control token returned when an upload-backed import was created.

minLength
1

Responses

200

The requested table import.

object

A durable table-import lifecycle resource.

1 field
dataobjectRequired

Response data.

14 fields
idstringRequired

Unique table-import identifier.

workspaceIdstringRequired

Workspace that owns the import.

statusstringRequired

Current import lifecycle state.

enum
["uploading","processing","completed","failed","canceled","expired"]
sourcevalueRequired

CSV source for the import.

Schema details

Exactly one of

Option 1object

CSV file uploaded through signed transfer instructions.

4 fields
typestringRequired

Upload-backed import discriminator.

const
upload
namestringRequired

CSV filename.

minLength
1
maxLength
255
contentTypestringRequired

CSV MIME type.

minLength
1
maxLength
255
sizeintegerRequired

Exact CSV file size in bytes.

minimum
1
maximum
5368709120

Additional properties are not allowed.

Option 2object

Existing workspace file used as a CSV import source.

2 fields
typestringRequired

Workspace-file source discriminator.

const
workspace_file
fileIdstringRequired

Existing workspace file identifier.

minLength
1

Additional properties are not allowed.

targetvalueRequired

New or existing table import target.

Schema details

Exactly one of

Option 1object
3 fields
typestringRequired

Create-new-table target discriminator.

const
new
namestringRequired

Name of the table to create.

minLength
1
maxLength
128
pattern
^[A-Za-z_][A-Za-z0-9_]*$
folderPathstring

Folder path. A missing leading slash is normalized before validation. Segments are percent-encoded, so a folder shown as "New folder" is /New%20folder: everything outside A-Z a-z 0-9 - _ . ~ is escaped as uppercase hex, and only that exact encoding is accepted. A trailing slash, an empty segment, and a literal . or .. segment are rejected. At most 64 segments and 4096 encoded bytes.

maxLength
4096

Additional properties are not allowed.

Option 2object
3 fields
typestringRequired

Existing-table target discriminator.

const
existing
tableIdstringRequired

Existing target table identifier.

minLength
1
modestringRequired

Whether to append rows or replace existing rows.

enum
["append","replace"]

Additional properties are not allowed.

tableIdvalueRequired

Resulting or target table identifier.

Schema details

Any of

Option 1string
Option 2null
rowsProcessedintegerRequired

Rows processed so far.

minimum
0
maximum
9007199254740991
rowsRejectedintegerRequired

Minimum number of source records dropped by parser failures. One failure can discard multiple records, such as an unterminated quote consuming the rest of the file. A non-zero value means partial import even with completed status; zero does not guarantee no loss.

minimum
0
maximum
9007199254740991
cellsRejectedintegerRequired

Non-empty cell values the target column type could not represent. Their rows were imported with the cell left blank.

minimum
0
maximum
9007199254740991
rejectedSamplesarrayRequired

Bounded sample of the dropped records, for locating them in the source file.

Schema details
Array itemobject

One source record a table import could not read.

3 fields
codestringRequired

CSV parser error code, e.g. CSV_QUOTE_NOT_CLOSED.

linevalueRequired

1-based source line the parser had reached when it gave up, or null.

Schema details

Any of

Option 1integer
minimum
0
maximum
9007199254740991
Option 2null
messagestringRequired

Parser message for the dropped record.

Additional properties are not allowed.

errorvalueRequired

Terminal failure reason, or null.

Schema details

Any of

Option 1string
Option 2null
createdAtstringRequired

ISO 8601 creation timestamp.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
updatedAtstringRequired

ISO 8601 last-update timestamp.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
completedAtvalueRequired

ISO 8601 completion timestamp, or null.

Schema details

Any of

Option 1string
format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Option 2null

Additional properties are not allowed.

Additional properties are not allowed.

Response headers

X-RateLimit-Limitinteger

Maximum requests allowed in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Remaininginteger

Requests remaining in the current window.

minimum
0
maximum
9007199254740991
X-RateLimit-Resetstring

ISO 8601 timestamp when the current rate-limit window resets.

format
date-time
pattern
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Was this helpful?
Suggest an edit