> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fuseai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Smart columns
> Ask a question about every row in a list and let Fuse research the answer
A [custom column](/guides/custom-columns) holds data you already have. A **smart column** holds data you do not: you write a question in plain English, and Fuse answers it for every row in the list.
Every endpoint here needs a key with the `lists` [scope](/concepts/scopes). Smart columns bill per row, so read [Bounding the spend](#bounding-the-spend) before running one over a large list.
## Two engines
The engine decides how the answer is found, and how much it costs.
Answers from the data already on the row and the model's own knowledge. Fast and cheap.
Researches each row against live sources before answering. Slower, costs more, and can be restricted to chosen providers.
## Create one
`POST /business/lists/{listId}/smart-columns` needs a `name`, a `prompt` and a `runOn`. It answers `202` — the column exists immediately, the answers arrive over the following minutes.
```bash theme={null}
curl -X POST https://api.tryfuse.ai/api/v1/business/lists/$LIST_ID/smart-columns \
-u "$FUSE_API_KEY:" \
-H "Content-Type: application/json" \
-d '{
"name": "Hiring signals",
"prompt": "Is this company hiring for sales roles right now? Answer yes or no and name the role.",
"engine": "standard",
"runOn": "first_100"
}'
```
```json theme={null}
{
"jobId": "68a1f6109c41d20014b3ec21",
"column": { "id": "68a1f3009c41d20014b3e9a1", "name": "Hiring signals", "engine": "standard" }
}
```
Keep the `jobId`. It is how you follow the run.
### Writing a prompt that answers well
The prompt is free text, and the shape of the answer follows the shape of the question. Ask for what you want back:
* **Say what a good answer looks like.** "Answer yes or no and name the role" produces a column you can filter on. "Tell me about their hiring" produces a paragraph.
* **Name the subject.** The row is a contact or a company; say which one you mean.
* **Keep it to one question.** Two questions in one prompt gives you two half-answers in one cell.
### Choosing what it runs on
`runOn` decides the initial scope, and it is the main lever on cost:
| `runOn` | Runs against |
| ----------- | ------------------------------------------------------------------ |
| `first_100` | The first 100 rows — the cheap way to see whether the prompt works |
| `all` | Every row in the list |
Start with `first_100`, read the answers, fix the prompt, then re-run over everything.
## Follow the run
`GET /business/lists/{listId}/smart-columns/{jobId}/status` reports progress and, importantly, what has been spent so far.
```json theme={null}
{
"job": {
"id": "68a1f6109c41d20014b3ec21",
"status": "processing",
"mode": "initial",
"runOn": "first_100",
"totalRows": 100,
"processedRows": 40,
"successfulRows": 38,
"failedRows": 2,
"creditsUsed": 76
}
}
```
Rows can fail individually — a company with nothing findable, a research provider timing out — and `failedRows` counts them. The job still completes; those cells stay empty.
## Read the answers
The values land on the list rows themselves. `GET /business/lists/{listId}/rows` returns them alongside every other column, so filtering, sorting and [exporting](/guides/export-a-list) all work on smart column output.
For a `deep_research` column you can also ask how an individual answer was reached:
```bash theme={null}
curl https://api.tryfuse.ai/api/v1/business/lists/$LIST_ID/rows/$CONTACT_ID/columns/$COLUMN_ID/provenance \
-u "$FUSE_API_KEY:"
```
```json theme={null}
{
"provenance": {
"reasoning": "The contact has 22 years of HR experience and currently holds a Recruitment Specialist role...",
"sourceUrls": ["https://www.linkedin.com/in/..."],
"fetchedAt": "2026-08-20T09:15:00.000Z"
}
}
```
That is the audit trail for an answer you intend to act on.
## Change the question
`PATCH /business/lists/{listId}/smart-columns/{columnId}` updates the name, prompt, engine or provider restriction.
Editing the **prompt** is not free. Fuse cancels whatever run is in flight and starts a billed refresh over the column's rows, because the old answers no longer match the question. The response carries a `jobId` when that happens — a rename returns `jobId: null`.
## Re-run it
`POST /business/lists/{listId}/smart-columns/{columnId}/rerun` fills answers in again. `mode` decides which rows:
| `mode` | Runs against |
| ---------- | ------------------------------------------------------------------------------ |
| `new_only` | Rows added since the last run — the cheap top-up after importing more contacts |
| `all` | Every row, replacing existing answers |
```json theme={null}
{ "jobId": "68a1f6109c41d20014b3ec22", "columnId": "68a1f3009c41d20014b3e9a1", "mode": "new_only" }
```
## Bounding the spend
Smart columns bill **per row answered**, and `deep_research` costs more than `standard`. Three habits keep it predictable:
Read the answers before spending on the whole list.
After an import, re-run only the new rows instead of the whole column.
The status endpoint reports spend while the run is still going, so a runaway prompt is visible before it finishes.
`GET /business/credits` shows the balance the run draws from. See [Credits](/concepts/credits).
## Errors worth handling
| Status | Code | Meaning |
| ------ | ---------------------- | ------------------------------------------------------ |
| `402` | `INSUFFICIENT_CREDITS` | Not enough credits for the rows this run would answer. |
| `404` | `LIST_NOT_FOUND` | The list id is not visible to your workspace. |
| `404` | `COLUMN_NOT_FOUND` | No smart column with that id on this list. |
| `409` | `COLUMN_NAME_TAKEN` | The list already has a column with that name. |