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

# List table runs

`GET /tables/{table_id}/runs/`

## 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}/runs/`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer

List a table's recompute runs with optional status and trigger filtering.

## Path parameters

- `table_id` string, uuid, required

## Query parameters

- `filters` ListTableRunsFilterParamsSchema, required: Query parameters for filtering table runs.
  - `status` 'pending' | 'running' | 'cancelling' | 'cancelled' | 'paused_for_credits' | 'completed' | 'completed_with_errors' | 'failed': 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``.
  - `trigger` 'cell_edited' | 'row_added' | 'row_manual' | 'column_added' | 'column_edited' | 'column_manual': What kind of mutation requested a recompute run.
- `limit` integer: The number of items to return.
- `order_by` 'id' | 'created_at' | 'updated_at'
- `order_direction` 'asc' | 'desc'
- `cursor` string, nullable: Set the cursor to the next or previous page. You can get the cursor from the previous page's response.

## Response `200`

Successful Response

- PaginatedResponseTableRunReadSchema
  - `data` TableRunReadSchema[]: The list of ResponseItems.
    - `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.
  - `next_page_cursor` string, nullable: The cursor to the next page. If there are no more pages, this is None.
  - `previous_page_cursor` string, nullable: The cursor to the previous page. If there are no previous pages, this is None.

## 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/dc5ac3c84444?raw)