Skip to main content
GET
/
v1
/
tables
List Tables
curl --request GET \
  --url https://api.extruct.ai/v1/tables \
  --header 'Authorization: Bearer <token>'
[
  {
    "id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "updated_at": "2023-11-07T05:31:56Z",
    "name": "<string>",
    "description": "<string>",
    "tags": [
      "<string>"
    ],
    "settings": {
      "exclude_from_search": false
    },
    "owner": {
      "id": "<string>",
      "email": "<string>"
    },
    "num_rows": 123
  }
]

​
Overview

This endpoint returns the root tables visible to the authenticated user. You can filter by table kind, ownership scope, free-text search, and tags. Results can be sorted by creation time, name, or row count.

​
Example request

export EXTRUCT_API_TOKEN="YOUR_API_TOKEN"

curl --get "https://api.extruct.ai/v1/tables" \
  -H "Authorization: Bearer ${EXTRUCT_API_TOKEN}" \
  --data-urlencode "scope=organization" \
  --data-urlencode "search=acme" \
  --data-urlencode "tags=portfolio" \
  --data-urlencode "tags=priority" \
  --data-urlencode "sort=-num_rows" \
  --data-urlencode "offset=0" \
  --data-urlencode "limit=20"

​
Key parameters

  • kind (optional): filter by table kind (generic, company, people).
  • scope (optional): filter by ownership. personal returns the caller’s own tables. organization returns all tables visible within the caller’s organization, including the caller’s own tables.
  • search (optional): case-insensitive search across table names and descriptions.
  • tags (optional): repeat this parameter to match tables with any of the selected tags.
  • sort (optional): one of -created_at, created_at, name, -name, num_rows, -num_rows.
  • offset (optional): number of matching tables to skip before returning results.
  • limit (optional): maximum number of tables to return. Defaults to 50; maximum is 100.

​
Success signal

A successful response returns an array of table objects. Each item includes summary fields such as id, created_at, updated_at, name, description, tags, kind, settings, scope, owner, and num_rows. The response also includes pagination headers:
  • x-extruct-pagination-total
  • x-extruct-pagination-total-pages
  • x-extruct-pagination-limit
  • x-extruct-pagination-offset
  • x-extruct-pagination-page

​
Common errors

​
401 Unauthorized

Check that your header is Authorization: Bearer ${EXTRUCT_API_TOKEN}.

​
400 Bad Request

Most often caused by limit values above 100.

​
422 Unprocessable Entity

Most often caused by unsupported query values for kind, scope, or sort.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
kind
enum<string> | null

Filter by table kind

Available options:
generic,
company,
people
​
scope
enum<string> | null

Filter by ownership: personal returns the caller's own tables; organization returns all tables visible within the caller's organization, including the caller's own tables.

Available options:
personal,
organization
​
search
string | null

Case-insensitive search across table names and descriptions.

​
tags
string[] | null

Repeat this parameter to match tables with any of the provided tags.

​
sort
enum<string> | null

Sort order for the returned tables.

Available options:
-created_at,
created_at,
name,
-name,
num_rows,
-num_rows
​
offset
integer | null

Number of matching tables to skip.

Required range: x >= 0
​
limit
integer | null
default:50

Maximum number of tables to return. Defaults to 50. Maximum 100.

Required range: 1 <= x <= 100

Response

Successful Response

​
id
string
required
​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
name
string
required
​
description
string | null
required
​
tags
string[] | null
required
​
kind
enum<string>
required
Available options:
generic,
company,
people
​
settings
TableSettings · object
required
​
scope
enum<string>
required

Ownership scope for filtering resources

Available options:
personal,
organization
​
owner
OwnerInfo · object
required
​
num_rows
integer
required