Cells and provenance
Cells hold row values and their available run provenance.
A cell is the current result of one column on one row. It is where you check source evidence, enrichment output, and qualification instead of treating a worksheet as an unexplained count. Use cells after a column or source run has finished, and before you scale a list or act on a result.
Cells sit in a worksheet under a workbook at /dashboard/workbooks. Their provenance connects a displayed value to the row, column, and work that produced it. Architect uses the diagnostics skill when a result is unclear, because a successful request is not proof that the cell contains the expected evidence.
Read a rectangle of real cells
Use tables.cells.read_page to read cells for the row ids and column ids you name. It is free and read-only. The read triggers no run and no provider call, which makes it the safe first step for checking a sample. It returns cells only, not row metadata and not per-cell diagnostics, so read the appropriate row or inspect capability when the question needs that context.
Each returned cell has a cell id, row id, column id, value, value type, nullable flag, status, run id, cost, provenance, observation time, update time, and history. Read a rectangle that contains representative rows and the columns that prove the qualification decision. This shows whether the worksheet has complete evidence rather than merely a favorable aggregate count.
| Cell field | What to inspect |
|---|---|
cell_id | Identifier for this cell result. |
row_id and column_id | The row and column that define the result. |
value and value_type | Current result and its declared type. |
nullable and status | Whether null is permitted and the current cell state. |
run_id and cost | Run context and cost information for the value. |
provenance | Evidence trail for how the value was produced. |
observed_at, updated_at, history | Observation, update, and retained history context. |
Read the row values, not only an aggregate. If an exact count is still being computed, it is unknown rather than zero. A report that claims the worksheet is landed, enriched, judged, or scored needs the finished run and a page of actual cells as evidence.
Separate cell states before acting
A worksheet can contain answered, empty, failed, and in-progress cells at the same time. These outcomes are not interchangeable. An empty cell means the answer is unknown. A missing provider answer is also unknown. Neither is false, neither is zero, and neither can be filled from a similar row just to make the worksheet look complete.
| State | Meaning and next check |
|---|---|
Answered | A value exists and carries the row, column, run, cost, and provenance context. |
Empty | No answer is known. Empty is not false, zero, or an answer copied from another row. |
Failed | The work did not settle a value. Read the owning run and structured error first. |
Queued or running | Work is still in progress. Read state again instead of treating it as a failure. |
Paced or capped | A workspace limit may be delaying work rather than reporting a defect. |
Read empty, failed, and answered results separately in the completion report. A required column with no data remains unknown. A failed cell needs an error or binding investigation. An answered cell still needs a quality check: confirm that the value actually proves the requested criterion rather than merely matching a keyword or label.
Queued, pending, paced, capped, and unknown are not failures by themselves. A cell blocked by a daily limit is a workspace pacing cap, not a defect. Do not retry an in-progress or unknown external action before you read the current run, because the provider work may already be under way or may have completed without the first read seeing it.
Keep the evidence trail with the value
Provenance is the evidence that explains how a cell reached its current value. A row source provides base data, and a column can project that data, derive it, judge it, or enrich it. Reading provenance alongside the value lets you distinguish a source-owned fact from a later judgment or provider response. When those pieces conflict, show both and investigate the binding or source route before deciding which result to use.
Let a column run settle cells whenever it can. Setting a value by hand bypasses the evidence trail and should be avoided when a column can produce the answer. A manual value is not a substitute for fixing a missing input, incorrect field reference, provider error, or wrong setting. The safest correction is at the source, binding, or run scope that caused the result.
Use links rather than copied evidence when a fact lives on another worksheet. In a company-and-people workbook, a person row should link to the company row that provides its qualifying signal. Re-typing a company’s evidence into a person cell makes the result stale when the source changes and makes it harder to trace the value back to its owner.
Check a representative sample against every named criterion. A row that matches a keyword but not the requested meaning, a person outside the named place, or a person not shown to work at the searched company is not a qualified row. Tighten the source or correct the column input, then read the next sample rather than changing the displayed cell manually.
Inspect the run that owns the result
Use runs.column_get to read counters attached to one canonical enrichment run. It is free and read-only. Its response wraps a run containing the API run id and status, total, processed, succeeded, failed, and skipped row counts, charged credits, and error_json. This is the record to inspect when cells have mixed results or a column appears to have stopped.
| Run field | How to use it |
|---|---|
status | Current execution state for the column run. |
total_rows | Rows in the canonical enrichment run. |
processed_rows | Rows the run has processed. |
succeeded_rows | Rows whose work succeeded. |
failed_rows and skipped_rows | Rows that failed or did not run. |
charged_credits | Credits charged by the run. |
error_json | Structured error data for diagnosis. |
Start from the specific cell, then its column, then the owning run. Record the link, state, attempt, provider, charged credits, and structured error when they answer the question. Stop reading when the cause is clear. A larger log dump does not make a diagnosis better, and it can hide the only row that needs a bounded correction.
A successful step with a receipt should not run again. If only some rows failed, retry the failed rows or failed node rather than re-running the entire sample. Follow a retry to a final result and read the resulting cells. This keeps successful work, prevents duplicate spend, and produces a clear evidence trail for the exception.
Complete the worksheet readback
A worksheet is not complete because a run was started. Completion evidence includes a finished source run, known landed and duplicate counts, finished enrichment runs, and a worksheet page that was actually read. Read at least three rows in full, inspect empty cells in every key column, and check duplicates on the entity identifier, such as a company domain or person profile URL.
When the goal is outreach to people, check that the People worksheet exists, holds person rows, and links them to qualifying companies. Companies alone do not complete a people request. When a result is ready, report the workbook link, sample size, qualification rate, charged credits, accounts still needing connection, and the specific next work, such as scaling, enrollment, or a scheduled refresh.
Read before every claim. A source run can succeed while a later qualification column is empty. A column run can succeed while its output is not relevant to the criterion. A count can exist while the individual rows show near misses. The completed readback keeps those distinctions visible to the operator and to Architect.
When a cell does not show the expected result
Use the diagnostics skill to choose one question and follow the smallest evidence chain that answers it. For an empty cell, check whether the column gate reads a column that has not settled, whether the column was added after rows landed and never run on them, or whether the provider returned no answer. For a stuck score, inspect the evidence column that failed or is still running.
For a failed cell, read the structured error and the binding inputs. Correct a missing input, wrong field reference, wrong setting, or connection problem at that level. For unexpectedly high credits, compare completed runs: the sample may have been run twice, contact data may have run before a fit gate, or an expensive column may precede a cheap selective one.
State the fix, whether it repeats external work or spends credits, and the result after it is checked. Cancel only a run the user wants stopped, then read its final state. If evidence indicates a product defect, do not hide it with another provider or a manual edit: retain the object and run identifiers required to report it.