Smart columns

A custom column 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. Smart columns bill per row, so read 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.

standard

Answers each row with a fast research agent that searches the web, reads pages and looks up LinkedIn profiles. Fast and cheap.

deep_research

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.

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"
  }'

{
  "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.
Plan for filtering. Row filters match text anywhere in a cell and ignore case. If you will filter on the answer, ask for exactly one word, such as yes or no, so a “no” answer can never contain “yes”. The qualify leads workflow shows the pattern end to end.

Choosing what it runs on

runOn decides the initial scope, and it is the main lever on cost:

`runOn`	Runs against
`first_1`, `first_10`, `first_100`, `first_1000`	That many rows, in the list’s current order — the cheap way to see whether the prompt works
`all`	Every row in the list

Start with first_100, read the answers and fix the prompt. Then re-run with new_only to answer the rest of the list without paying for the sample rows twice. Add filters, in the same row filter language as GET /business/lists/{listId}/rows, to cover only matching rows. A filter that matches nothing is refused with 422 NO_ROWS_TO_RESEARCH before anything is charged.

Follow the run

GET /business/lists/{listId}/smart-columns/{jobId}/status reports progress and, importantly, what has been spent so far.

{
  "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 run still finishes, as partially_completed, and those cells stay empty. Poll until status is completed, partially_completed, failed or cancelled; a run is cancelled when a newer run or a prompt edit replaces it.

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 all work on smart column output. For any smart column you can also ask how an individual answer was reached:

curl https://api.tryfuse.ai/api/v1/business/lists/$LIST_ID/rows/$CONTACT_ID/columns/$COLUMN_ID/provenance \
  -u "$FUSE_API_KEY:"

{
  "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. Personalize every email with AI research uses it to check opening lines before they are sent.

Change the question

PATCH /business/lists/{listId}/smart-columns/{columnId} updates the name, prompt or provider restriction. The engine is fixed when the column is created, so sending engine is a 422.

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 that have never been answered: the rows the first run’s `runOn` left out, plus rows added since. The cheap way to finish a list or top it up after an import.
`all`	Every row, replacing existing answers

mode defaults to all, the more expensive choice. Either mode cancels a run that is still in progress. The balance must cover every row the run will answer before it starts, and each row is then charged as it is answered. GET /business/lists/{listId}/smart-columns/{columnId} shows creditsPerRow, so you can price a run before you start it.

{ "jobId": "68a1f6109c41d20014b3ec22", "columnId": "68a1f3009c41d20014b3e9a1", "mode": "new_only" }

Bounding the spend

Smart columns bill per row answered: 20 credits a row with standard and 100 with deep_research. Rows that fail are free. Three habits keep it predictable:

Prototype on first_100

Read the answers before spending on the whole list.

Top up with new_only

After an import, re-run only the new rows instead of the whole column.

Watch creditsUsed on the job

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.

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.
`404`	`JOB_NOT_FOUND`	No smart column run with that `jobId`.
`404`	`PROVENANCE_NOT_FOUND`	That cell has no computed answer yet.
`409`	`COLUMN_NAME_TAKEN`	The list already has a column with that name.
`422`	`COLUMN_NAME_RESERVED`	The name belongs to a built-in column.
`422`	`PROVIDERS_NOT_SUPPORTED`	`providerIds` was sent for a `standard` column. Only `deep_research` columns take a provider restriction.
`422`	`NO_ROWS_TO_RESEARCH`	No row matches `filters`, or a `new_only` re-run has nothing left to answer. Nothing was charged.

Get started

Concepts

Guides

Workflows

CRM sync

Power dialer

Deep Research

Signals

MCP server

Two engines

standard

deep_research

Create one

Writing a prompt that answers well

Choosing what it runs on

Follow the run

Read the answers

Change the question

Re-run it

Bounding the spend

Errors worth handling

​Two engines

standard

deep_research

​Create one

​Writing a prompt that answers well

​Choosing what it runs on

​Follow the run

​Read the answers

​Change the question

​Re-run it

​Bounding the spend

​Errors worth handling

Two engines

Create one

Writing a prompt that answers well

Choosing what it runs on

Follow the run

Read the answers

Change the question

Re-run it

Bounding the spend

Errors worth handling