---
title: "List tables (cursor-paginated; ?workspaceId=)"
method: GET
path: "/tables"
tags: ["Workspace"]
---

# List tables (cursor-paginated; ?workspaceId=)

`GET /tables`

## Query parameters

- `cursor` string
- `limit` integer
- `workspaceId` string, uuid

## Response `200`

A page of TableObjects in the canonical list envelope.

- object — The canonical v2 list envelope. Every list endpoint returns this shape; per-endpoint `items` element types (and documented extras like `total`) are declared on each operation.
  - `object` 'list', required
  - `items` Table[], required — The page of objects. Element type is per-endpoint.
    - `object` 'table', required
    - `id` string, uuid, required
    - `workspaceId` string, uuid, required
    - `name` string, required
    - `leadCount` integer, required — Non-deleted row count. v2 wire vocabulary speaks "leads" instead of "rows"; the underlying DB column is still `rows`.
    - `columns` TableColumn[], required
      - `object` 'column', required
      - `id` string, uuid, required
      - `name` string, required
      - `type` string, required — Raw DB column type. Common values: `static` (user-entered), `code` (user-TS that runs per row, includes enrichments, scoring, and sequence columns), plus other internal-typed kinds for future extensibility. Treat as an open string. Prefer `kind` for classification — it splits `code` columns into `enrichment`, `score`, and `sequence`.
      - `kind` 'input' | 'enrichment' | 'score' | 'sequence', required — Sequence-aware API classification of a column: * `input` — user-entered (`static`) column; the only kind writable via `POST /tables/{tableId}/rows/upsert`. * `enrichment` — `code` column that runs per row to fetch/compute a value. * `score` — relevance / fit-score column. * `sequence` — `code` column that drafts an outbound sequence (`ctx.upsertSequence(...)` / `.draftMessage(...)`, or one that already has sequences). List its sequences via `GET /tables/{tableId}/sequences`. Created via the agent or column code only — never via the upsert API.
      - `slug` string, nullable, required — Stable url-safe slug, or null when the column has none.
      - `autoTrigger` boolean, required — True when the column runs automatically on new leads. False for columns that only run when explicitly invoked (e.g. exports, manual-trigger code columns).
      - `credits` CreditsLifetime, required
        - `lifetimeUsed` integer, required — Sum of all settled cell-run charges, in credits. Stable and additive — once a row enrichment finishes it never moves backwards. Reservations (in-flight cell_runs) are not included.
      - `cells` CellsLiveness, required — Snapshot of cell-pipeline activity. The v2 run-finished signal is independent of the cell-pipeline-finished signal — when a run completes, downstream cells often still enrich in the background. Surfacing these counts lets the agent distinguish "still working on it" from "tried and failed", which is the difference between waiting and reporting a negative result.
        - `running` integer, required — Number of cells currently being processed (a `cell_run` is in `waiting`, `queued`, or `running` for that cell). `running > 0` means the agent should NOT report "no data found" — wait and re-read.
        - `errored` integer, required — Number of cells that hit a settled failure. Includes `errored`, `out_of_credits`, `subscription_required`, and `connection_required`. The user-driven `stopped` state is intentionally excluded — it's a cancellation, not a failure to surface.
      - `stats` ColumnStats
        - `avgCreditsPerRun` number, required — Average credits charged when this column actually runs.
        - `callRate` number, required — Fraction of leads that triggered this column (0-1).
        - `totalRuns` integer, required — Lifetime count of cell runs feeding the average.
      - `qualification` ColumnQualification
        - `pass` integer, required
        - `fail` integer, required
        - `unsure` integer, required
        - `total` integer, required
    - `credits` CreditsLifetime, required
      - `lifetimeUsed` integer, required — Sum of all settled cell-run charges, in credits. Stable and additive — once a row enrichment finishes it never moves backwards. Reservations (in-flight cell_runs) are not included.
    - `cells` CellsLiveness, required — Snapshot of cell-pipeline activity. The v2 run-finished signal is independent of the cell-pipeline-finished signal — when a run completes, downstream cells often still enrich in the background. Surfacing these counts lets the agent distinguish "still working on it" from "tried and failed", which is the difference between waiting and reporting a negative result.
      - `running` integer, required — Number of cells currently being processed (a `cell_run` is in `waiting`, `queued`, or `running` for that cell). `running > 0` means the agent should NOT report "no data found" — wait and re-read.
      - `errored` integer, required — Number of cells that hit a settled failure. Includes `errored`, `out_of_credits`, `subscription_required`, and `connection_required`. The user-driven `stopped` state is intentionally excluded — it's a cancellation, not a failure to surface.
    - `url` string, uri, required — Deep link a human can open. For programmatic row reads, use `GET /api/v2/tables/{tableId}/rows`.
    - `createdAt` string, date-time, required
    - `updatedAt` string, date-time, required
    - `stats` TableStats — Forward-looking table economics — the same numbers the desktop UI shows at the top of the table. Only present on responses that opted in via `?include=stats`.
      - `creditsPerLead` number, required — Estimated credits per sourced lead (pre-qualification).
      - `creditsPerQualifiedLead` number, required — Estimated credits per qualified lead, including the loss from dedup, exclusion, and filter cascade.
      - `findMoreEstimatedCredits` number, required — Per-execution cost of the "Find More" code, in credits.
      - `qualification` TableQualificationStats, required
        - `rate` number, nullable, required
        - `fetchRate` number, nullable, required — Filter-only qualification rate (excludes dedup / exclusion).
        - `qualifiedLeads` integer, required
        - `effectiveLeadsPerQualified` number, required — Empirical leads-processed per qualified lead.
        - `estimatedQualifiedLeads` integer, nullable, required
      - `funnel` TableFunnelStats, required
        - `totalSourcedLeads` integer, required
        - `postStaticLeads` integer, required — Leads surviving dedup + exclusion + required static filters.
        - `dedupedLeads` integer, required
        - `dedupRate` number, nullable, required
        - `excludedLeads` integer, required
        - `excludedRate` number, nullable, required
      - `running` TableRunningStats, required
        - `runningLeads` integer, required — Leads with active (queued / running / waiting) cell runs.
        - `oldestActiveRunStartedAt` string, date-time, nullable, required
      - `leadSources` TableLeadSourceStats[], required
        - `id` string, uuid, required
        - `name` string, required
        - `avgCreditsPerLead` number, required
        - `totalCredits` number, required
        - `totalLeads` integer, required
        - `source` 'historical' | 'estimate', required — `historical` when the average is derived from real cost_events; `estimate` when it was computed by static regex analysis of the lead source's TypeScript code.
      - `hasUnknownTotalWithMore` boolean, required — True when ≥1 active lead source has unknown TAM AND `has_more=true` (e.g. Twitter / LinkedIn post search). Consumers should render "X found (more available)" instead of a numeric TAM when set.
  - `nextCursor` string, nullable, required — Cursor for the next page; `null` means this is the last page.
  - `url` string, required — The path this list was fetched from (query string excluded).

---

[API](https://skmtc.net/origami/apis/origami-agent-api.md) · [All operations](https://skmtc.net/origami/apis/origami-agent-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/origami/origami-agent-api/versions/8083ad7fe081/schema)