Skip to content
Try for free
On this page

Tables

List tables

List active tables with folder filtering, search, sorting, and cursor pagination. Use `scope=archived` to find tables available for restoration. Workspace folder trees exceeding 10,000 folders return `413`. OAuth scope: `api:read`.

GET/api/v2/tables

List active tables with folder filtering, search, sorting, and cursor pagination. Use scope=archived to find tables available for restoration. 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.

Query parameters

workspaceIdstringRequired

Workspace whose tables should be listed.

minLength
1
maxLength
128
scopestring

Which lifecycle set to list: active (default) for live tables, archived for tables a delete archived and a table restore can bring back. folderPath resolves against active folders only, so pairing it with scope=archived returns an empty page when the containing folder was archived too.

default
active
enum
["active","archived"]
folderPathstring

Restrict results to tables in this folder. Unknown folder paths contribute no matches.

maxLength
4096
searchstring

Case-insensitive substring match against the resource name.

minLength
1
maxLength
200
sortBystring

Field used to sort the result. Do not rely on case-insensitive ordering when sorting by name.

default
createdAt
enum
["name","createdAt","updatedAt"]
sortOrderstring

Sort direction.

default
asc
enum
["asc","desc"]
limitinteger

Maximum tables to return per page. Values outside 1–1000 are truncated and clamped into that range rather than rejected. Defaults to 100.

default
100
cursorstring

Opaque cursor from the previous page. Send it back with the same sort and filters; only limit may change. Change anything else and pagination must restart without a cursor.

minLength
1

Responses

200

A page of tables in the workspace.

object

A cursor-paginated page of tables.

2 fields
dataarrayRequired

Items in the current page.

Schema details
Array itemobject

A user-defined table with typed columns and governance state.

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.

nextCursorvalueRequired

Opaque cursor for the next page. Send it back as cursor; null means there are no more pages. Do not construct a cursor yourself.

Schema details

Any of

Option 1string
Option 2null

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