---
title: "Get a table — name, leadCount, columns, credits, optional economics"
method: GET
path: "/tables/{tableId}"
tags: ["Tables"]
---

# Get a table — name, leadCount, columns, credits, optional economics

`GET /tables/{tableId}`

The canonical "what's in this table and what did it cost?"
surface in v2. Same shape as the entries in
`Run.response.tables[]` and `GET /agents/{id}/tables`.

Default shape is lite — `leadCount`, `columns[]` with
per-column `credits.lifetimeUsed`, table-level
`credits.lifetimeUsed` (sum of the column breakdown). Pass
`?include=stats` to attach the economics block — the same
numbers the UI shows at the top of the table
(creditsPerLead, qualification breakdown, funnel, lead
sources, ...).

`credits.lifetimeUsed` accumulates across every agent run
that ever populated cells on this table — it is the unit a
human thinks in when they ask how much a list cost. It does
NOT include still-active cell-run reservations; wait for the
relevant run to terminate before reading the final number.

Scoped to the API key's org. There is no API-owned filter on
tables, so any non-deleted table in your org is fetchable.
For programmatic row reads, use
[`GET /api/v2/tables/{tableId}/rows`](https://origami.chat/reading-data).

## Query parameters

- `include` string

## Response `200`

The table object

- Table
  - `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.

## Other responses

- `404` — Table not found in this org (or soft-deleted)

---

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