---
title: "List tables in the agent's workspace"
method: GET
path: "/agents/{id}/tables"
tags: ["Tables"]
---

# List tables in the agent's workspace

`GET /agents/{id}/tables`

The fallback discovery surface in v2. The run object only
carries `response.tables[]` for tables a specific run
*touched* (empty when the run made no mutations or stopped on
a question), so callers that need "every table this agent has
access to" use this endpoint instead.

Each entry is a full TableObject — same shape as
`GET /api/v2/tables/{id}` and the same shape embedded under
`Run.response.tables[]`. Pass `?include=stats` to attach the
economics block (per-table + per-column).

Scoped to the agent's own workspace; a caller cannot probe
arbitrary workspaces through this path. Returned in the
canonical list envelope with `nextCursor` always `null` — an
agent's workspace is rarely more than a handful of tables, so
the endpoint does not paginate.

## Query parameters

- `include` string

## Response `200`

Tables in the agent's workspace (list envelope + `workspaceId`).

- 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).
  - `workspaceId` string, uuid, required

## Other responses

- `404` — Agent not found (or belongs to another org)

---

[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/revisions/8083ad7fe081/schema)