---
title: "Get table stats"
method: GET
path: "/tables/{table_id}/stats/"
tags: ["tables"]
---

# Get table stats

`GET /tables/{table_id}/stats/`

## Request

- Base URL: `https://api.getoneprofile.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getoneprofile.ai/tables/{table_id}/stats/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

Get aggregate stats for one table: row count, columns per kind, failed cell count, the newest active run (if any), and whether the table is at its row cap.

## Path parameters

- `table_id` string, uuid, required

## Response `200`

Successful Response

- TableStatsSchema: Aggregate stats for one table, composed from three downward reads.
  - `active_run` TableRunReadSchema, required: A table recompute run with its static denominator and monotone counters.
    - `cells_awaiting` integer, required: Cells the run held because an input they read has not been computed yet. Not a final state: a later run fills them. Counted within cells_done.
    - `cells_done` integer, required: Cells processed so far; clamped to cells_total so the banner can never overshoot.
    - `cells_failed` integer, required: Cells whose formula evaluation failed.
    - `cells_no_data` integer, required: Cells that ran clean but found nothing. Never retried, and excluded from errored views. Free for a lookup; an AI column's cell is charged what it used. Counted within cells_done.
    - `cells_skipped` integer, required: Cells the run deliberately skipped: a missing required input or a false run condition. Counted within cells_done.
    - `cells_total` integer, required: Exact static denominator, fixed when the run plan is minted.
    - `column_id` string, uuid, nullable: The column a column-lineage run recomputes, parsed from its workflow identity; null for whole-table runs. Narrows the grid's busy paint to one column; `row_scope` is what narrows it to the rows within that column.
    - `column_ids` string[], nullable: Every column this run's plan covers, in dependency (layer) order, not the order they were requested in. Null on runs minted before the plan was published, where column_id is all there is. This is what narrows the grid's busy paint when one run covers several columns, which column_id cannot express.
    - `completed_at` string, date-time, nullable, required
    - `created_at` string, date-time, required
    - `credits_charged` number: Credits charged so far. Grows while the run works, as its finished cells are settled every few seconds; final once the run ends.
    - `error` string, nullable, required: Failure description when the run status is failed.
    - `export_retry_attempt` integer: How many automatic export retries preceded this run. 0 is a run a person or a schedule asked for; higher values mark the follow-ups queued for rows whose push failed for a retryable reason, so a run history can tell 'we tried again' from 'you ran it again'.
    - `id` string, uuid, required
    - `row_scope` TableRunRowScopeReadSchema, required: The rows a run resolved to: what lets a client mark exactly those busy. ``record_ids`` is populated for the ``record_ids`` kind alone. ``all_rows`` and ``unlisted`` both mean "assume every row": the first because it is true, the second because the set was too large to carry on every frame. Collapsing them keeps a client's fallback one branch rather than two.
      - `kind` 'all_rows' | 'record_ids' | 'unlisted', required: How a minted run's RESOLVED row set is published to readers. Distinct from :class:`TableRunScope`, which is what the caller ASKED for. The two disagree routinely (``ALL`` on a ``keep_existing_results`` table is silently narrowed to the unfilled rows at mint) and only the resolved set can be painted, so only the resolved set is stored. ``UNLISTED`` is a real row subset whose ids were too many to carry on every changefeed frame (see ``max_persisted_scope_rows``). It reads exactly like ``ALL_ROWS`` to a client: assume every row. That keeps the fallback one branch rather than two, at the cost of over-painting the rare huge partial.
      - `record_ids` string[], nullable, required: The exact rows the run will touch; null unless kind is record_ids.
      - `rows` integer, nullable, required: Rows the resolved scope covers; null for all rows.
    - `started_at` string, date-time, nullable, required
    - `status` 'pending' | 'running' | 'cancelling' | 'cancelled' | 'paused_for_credits' | 'completed' | 'completed_with_errors' | 'failed', required: Lifecycle status of a table run. ``PENDING`` exists for API compatibility but is never observed: runs are born ``RUNNING`` at mint. ``CANCELLING`` is the requested-stop state the page activities observe; the workflow finalizes it to ``CANCELLED``.
    - `table_id` string, uuid, required
    - `trigger` 'cell_edited' | 'row_added' | 'row_manual' | 'column_added' | 'column_edited' | 'column_manual', required: What kind of mutation requested a recompute run.
  - `at_row_cap` boolean, required: Whether the table has reached its row cap.
  - `cell_settlement_by_column` object: How each column's cells ended, per column ID. A column with no cells is absent; read absence as zero across every figure. The completeness read. `filled_cells_by_column` and `failed_cells_by_column` are both projections of this and are kept only so an existing API-key client does not break.
  - `columns_by_kind` object, required: Number of columns per column kind (manual/formula).
  - `failed_cells` integer, required: Cells currently carrying an evaluation error.
  - `failed_cells_by_column` object, required: Errored cells per column ID. A column with no failures is absent; read absence as zero. What the column header's error badge shows.
  - `filled_cells_by_column` object, required: Cells holding a stored value, per column ID. A column with no filled cells is absent; read absence as zero. How much of the column has DATA in it, which is not how much of it is DONE. For that, and for the breakdown behind it, read `cell_settlement_by_column`.
  - `last_run_at_by_column` object: When each column last produced a value. Derived from its newest computed cell. A column absent here has never run. Not the column's updated_at, which moves when it is merely renamed.
  - `row_count` integer, required

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Table not found
- `422`: Invalid request made to the API.
- `500`: Internal server error.
- `502`: Bad gateway error.
- `503`: Service unavailable.

---

[API](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile.md) · [All operations](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/llms.txt) · [OpenAPI document](https://skmtc.dev/getoneprofile/apis/api-reference-oneprofile/revisions/4a6bd71e3f02?raw)