--- title: "Add an AI column that researches every row" method: POST path: "/business/lists/{listId}/smart-columns" tags: ["Smart columns"] --- # Add an AI column that researches every row `POST /business/lists/{listId}/smart-columns` ## Request - Base URL: `https://api.tryfuse.ai/api/v1` - URL: `https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns` - Auth: HTTP basic Adds a smart column to the list and starts its first run. Every covered row is researched from `prompt` by the chosen `engine` and billed at that engine's per-row credit rate; the run is charged up front, so the call answers 402 INSUFFICIENT_CREDITS when your balance cannot cover it and nothing is created. `runOn` bounds the first run (`first_1` … `first_1000` rows in the list's current order, or `all`) and `filters` narrows the rows it may cover; run the column again later (`POST …/smart-columns/{columnId}/rerun` with `mode: new_only`) to fill the rest. `engine: deep_research` uses the multi-provider Deep Research pipeline at a higher per-row rate and is the only engine that accepts a `providerIds` restriction (provider slugs from `GET /business/research/providers`); `standard` (default) is the per-row web-research agent. The name must be free on the list (409 COLUMN_NAME_TAKEN) and must not be a reserved built-in column name (422 COLUMN_NAME_RESERVED), and a filter that matches no row is rejected with 422 NO_ROWS_TO_RESEARCH before anything is charged. The call is asynchronous: it answers 202 with the run's `jobId` and the new column. Poll `GET /business/lists/{listId}/smart-columns/{jobId}/status` until `status` is `completed`, `partially_completed`, `failed` or `cancelled`, then read the values from `GET /business/lists/{listId}/rows` (`columnValues[columnId]`) and each cell's sources from the provenance endpoint. Errors: - `402` `INSUFFICIENT_CREDITS` — Your credit balance cannot cover the run (covered rows × the engine's per-row rate); nothing was started or charged. - `404` `LIST_NOT_FOUND` — No list with that id belongs to you. - `409` `COLUMN_NAME_TAKEN` — A column with this name already exists on the list. - `422` `COLUMN_NAME_RESERVED` — The name is one of the reserved built-in column names (name, first name, last name, job title, company, email, phone …). - `422` `PROVIDERS_NOT_SUPPORTED` — providerIds was sent for the standard engine; only a deep_research column can be restricted to specific providers. - `422` `NO_ROWS_TO_RESEARCH` — No row on the list matches `filters`, so there is nothing to research and nothing was charged. - `422` `INVALID_REQUEST` — CRM rejected the column definition for a reason with no more specific code. - `422` `VALIDATION_FAILED` — The path, query or body failed validation; `param` names the offending field and `message` says why. - `429` `RATE_LIMITED` — More than 120 requests per minute or 10,000 per day on the lists bucket, which every /business/lists endpoint shares; retry after Retry-After. - `500` `UNEXPECTED_ERROR` — The request could not be completed; quote request_id to support. Requires one of the following token scopes: lists. ## Path parameters - `listId` string, required: 24-character hex id of the list (from GET /business/lists). ## Request body - object - `name` string, required: Display name of the new column (1-100 characters, trimmed). Must be unique on the list and must not be a reserved built-in column name such as name, first name, last name, job title, company, email or phone. - `prompt` string, required: The research instruction the engine answers once per covered row (1-2000 characters, trimmed); the answer is written into that row's cell and its sources are kept as provenance. - `runOn` 'first_1' | 'first_10' | 'first_100' | 'first_1000' | 'all', required: How many rows the first run covers, taken in the list's current order after `filters`: first_1, first_10, first_100 or first_1000 take that many rows; all covers every row. Every covered row is billed at the engine's per-row credit rate up front; rerun the column later for the rest. - `engine` 'standard' | 'deep_research': Engine that researches each row: standard (default) is the fast per-row web-research agent; deep_research is the multi-provider Deep Research pipeline, billed at a higher per-row rate, and the only engine that accepts providerIds. - `filters` object: Optional row filter in the same JSON row-filter language as the `filters` query of GET /business/lists/{listId}/rows (built-in fields by canonical key, custom and smart columns under customColumns keyed by column id); only matching rows are covered. Omit to cover the whole list. - `providerIds` string[]: deep_research only: restrict the research to these provider ids, each the `id` of an entry returned by GET /business/research/providers. The ids are an allowlist, not an order: the run may call any of them, chooses per row, and need not use them all; the order you send them in is ignored. Send 1 to 50 distinct ids — an empty array or a repeated id is rejected. Ids are never checked against the catalog: a typo, a provider whose `allowedInRuns` is false, or a `byok-required` provider you have not saved a key for is accepted and then silently dropped from the run, and if none of the ids survive that check the rows are researched only by the providers Fuse always includes, so the answers come back far thinner than you asked for with no error anywhere. Sent with engine standard the call is rejected with 422 PROVIDERS_NOT_SUPPORTED. Omit to let the run use every provider available to your workspace. ## Response `202` Success - object - `jobId` string, nullable, required: Id of the run that was started; poll it on GET /business/lists/{listId}/smart-columns/{jobId}/status. - `column` object, required - `id` string, nullable, required: Id of the new column (the columnId used by every other smart-column endpoint). - `name` string, required: The column name as sent. - `engine` 'standard' | 'deep_research', required: The engine the column runs on. ## Other responses - `400`: Error - `401`: Error - `402`: Error - `403`: Error - `404`: Error - `409`: Error - `422`: Error - `429`: Error - `500`: Error --- [API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)