curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"prompt": "<string>"
}
'import requests
url = "https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns"
payload = {
"name": "<string>",
"prompt": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', prompt: '<string>'})
};
fetch('https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"jobId": "68a1f6109c41d20014b3ec21",
"column": {
"id": "68a1f3009c41d20014b3e9a1",
"name": "Hiring signals",
"engine": "standard"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}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:
402INSUFFICIENT_CREDITS— Your credit balance cannot cover the run (covered rows × the engine’s per-row rate); nothing was started or charged.404LIST_NOT_FOUND— No list with that id belongs to you.409COLUMN_NAME_TAKEN— A column with this name already exists on the list.422COLUMN_NAME_RESERVED— The name is one of the reserved built-in column names (name, first name, last name, job title, company, email, phone …).422PROVIDERS_NOT_SUPPORTED— providerIds was sent for the standard engine; only a deep_research column can be restricted to specific providers.422NO_ROWS_TO_RESEARCH— No row on the list matchesfilters, so there is nothing to research and nothing was charged.422INVALID_REQUEST— CRM rejected the column definition for a reason with no more specific code.422VALIDATION_FAILED— The path, query or body failed validation;paramnames the offending field andmessagesays why.429RATE_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.500UNEXPECTED_ERROR— The request could not be completed; quote request_id to support.
Requires one of the following token scopes: lists.
curl --request POST \
--url https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"prompt": "<string>"
}
'import requests
url = "https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns"
payload = {
"name": "<string>",
"prompt": "<string>"
}
headers = {
"Authorization": "Basic <encoded-value>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Basic <encoded-value>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: '<string>', prompt: '<string>'})
};
fetch('https://api.tryfuse.ai/api/v1/business/lists/{listId}/smart-columns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"jobId": "68a1f6109c41d20014b3ec21",
"column": {
"id": "68a1f3009c41d20014b3e9a1",
"name": "Hiring signals",
"engine": "standard"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}{
"error": {
"code": "<string>",
"message": "<string>",
"param": "<string>",
"doc_url": "<string>",
"request_id": "<string>"
}
}Authorizations
Your API token (af_…) as the Basic-auth username, with an empty password.
Path Parameters
24-character hex id of the list (from GET /business/lists).
Body
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.
1 - 100The 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.
1 - 2000How 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.
first_1, first_10, first_100, first_1000, all 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.
standard, deep_research 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.
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.
1 - 50 elementsA Deep Research provider id: the id (catalog slug, for example zerobounce) of an entry returned by GET /business/research/providers, not a Mongo id.
1 - 64