Skip to content
Try for free
On this page

Tables

Get table

Get a table with its metadata, column schema, locks, and current job. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:read`.

GET/api/v2/tables/{tableId}

Get a table with its metadata, column schema, locks, and current job. Workspace folder trees exceeding 10,000 folders return 413.

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

tableIdstringRequired

Unique table identifier.

minLength
1

Query parameters

workspaceIdstringRequired

Workspace that owns the table.

minLength
1

Responses

200

The requested table.

object

A single table.

1 field
dataobjectRequired

Response data.

13 fields
idstringRequired

Unique table identifier.

webUrlstringRequired

Canonical absolute URL for opening this resource in the Sim web application.

format
uri
namestringRequired

Table name.

descriptionvalueRequired

Table description, or null when none is set.

Schema details

Any of

Option 1string
Option 2null
ownerEmailstringRequired

Current email address of the table owner.

format
email
pattern
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$
schemaobjectRequired

Typed table schema.

1 field
columnsarrayRequired

Table column definitions.

Schema details
Array itemobject

A typed column in a table schema.

9 fields
idstring

Stable server-assigned column identifier.

namestringRequired

Column name used as the public row-data key.

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

Data type of values stored in the column.

enum
["string","number","currency","boolean","date","json","select"]
requiredbooleanRequired

Whether inserts require a value for this column.

default
false
uniquebooleanRequired

Whether values must be unique across table rows.

default
false
workflowGroupIdstring

Workflow group whose output populates this column.

optionsarray

Options declared for a select column.

maxItems
100
Schema details
Array itemobject
2 fields
idstringRequired

Stable select-option identifier.

minLength
1
namestringRequired

Display name of the select option.

minLength
1
maxLength
100

Additional properties are not allowed.

multipleboolean

Whether a select column accepts multiple options.

currencyCodestring

ISO 4217 code for a currency column, normalized to uppercase.

pattern
^[A-Za-z]{3}$

Additional properties are not allowed.

Additional properties are not allowed.

rowCountnumberRequired

Current number of rows in the table.

maxRowsnumberRequired

Maximum rows allowed by the workspace plan.

folderPathstringRequired

Canonical slash-prefixed folder path. / is the workspace root. 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
locksobjectRequired

Read-only table governance locks.

4 fields
schemaLockedbooleanRequired

Whether column-schema changes are locked.

insertLockedbooleanRequired

Whether row insertion is locked.

updateLockedbooleanRequired

Whether row updates are locked.

deleteLockedbooleanRequired

Whether row and table deletion is locked.

Additional properties are not allowed.

jobvalueRequired

Current background job, or null when idle.

Schema details

Any of

Option 1object

Current background work associated with a table.

5 fields
idvalueRequired

Background job identifier, or null when unavailable.

Schema details

Any of

Option 1string
Option 2null
typevalueRequired

Kind of background table work.

Schema details

Any of

Option 1string
enum
["import","delete","export","backfill","update"]
Option 2null
statusstringRequired

Current background job state.

enum
["running","ready","failed","canceled"]
rowsProcessednumberRequired

Number of rows processed by the job.

errorvalueRequired

Failure reason, or null when the job has not failed.

Schema details

Any of

Option 1string
Option 2null

Additional properties are not allowed.

Option 2null
createdAtstringRequired

ISO 8601 timestamp when the table was created.

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 timestamp when the table was last modified.

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))$

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