> ## 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. # Add an AI column that researches every row > 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. ## OpenAPI ````yaml /openapi.json post /business/lists/{listId}/smart-columns openapi: 3.1.0 info: title: Fuse Business API version: 1.0.0 description: >- External API for lists, campaigns, prospect search and contacts. Authenticate with your API token as HTTP Basic. All paths are under /api/v1. servers: - url: https://api.tryfuse.ai/api/v1 description: Production security: - basicAuth: [] tags: - name: Lists - name: Custom columns - name: Smart columns - name: Exports - name: Campaigns - name: Knowledge hubs - name: Analytics - name: Website intent - name: Account - name: Prospect search - name: Campaign steps - name: Scheduled sends - name: Campaign templates - name: Agents - name: Research - name: Company search - name: Saved searches - name: Folders - name: Contacts paths: /business/lists/{listId}/smart-columns: post: tags: - Smart columns summary: Add an AI column that researches every row description: >- 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. operationId: createSmartColumn parameters: - name: listId in: path required: true description: 24-character hex id of the list (from GET /business/lists). schema: type: string description: 24-character hex id of the list (from GET /business/lists). requestBody: required: true content: application/json: schema: type: object properties: name: type: string minLength: 1 maxLength: 100 description: >- 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: type: string minLength: 1 maxLength: 2000 description: >- 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: type: string enum: - first_1 - first_10 - first_100 - first_1000 - all description: >- 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: type: string enum: - standard - deep_research default: standard description: >- 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: type: object properties: {} description: >- 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: type: array items: type: string minLength: 1 maxLength: 64 description: >- A Deep Research provider id: the `id` (catalog slug, for example `zerobounce`) of an entry returned by GET /business/research/providers, not a Mongo id. minItems: 1 maxItems: 50 description: >- 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. required: - name - prompt - runOn responses: '202': description: Success headers: RateLimit-Limit: schema: type: integer description: Requests permitted in the current window. RateLimit-Remaining: schema: type: integer description: Requests remaining in the current window. RateLimit-Reset: schema: type: integer description: Seconds until the current window resets. content: application/json: schema: type: object required: - jobId - column properties: jobId: type: - string - 'null' description: >- Id of the run that was started; poll it on GET /business/lists/{listId}/smart-columns/{jobId}/status. column: type: object required: - id - name - engine properties: id: type: - string - 'null' description: >- Id of the new column (the columnId used by every other smart-column endpoint). name: type: string description: The column name as sent. engine: type: string enum: - standard - deep_research description: The engine the column runs on. example: jobId: 68a1f6109c41d20014b3ec21 column: id: 68a1f3009c41d20014b3e9a1 name: Hiring signals engine: standard '400': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '402': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Error content: application/json: schema: $ref: '#/components/schemas/Error' security: - basicAuth: [] components: schemas: Error: type: object properties: error: type: object properties: code: type: string message: type: string param: type: - string - 'null' doc_url: type: - string - 'null' request_id: type: - string - 'null' required: - code - message required: - error securitySchemes: basicAuth: type: http scheme: basic description: >- Your API token (`af_…`) as the Basic-auth username, with an empty password. ````