Smart Agents

A smart agent runs one AI instruction on each lead in a lead list and writes the result into a column of that list, one AI call per lead. In the app, the same per-row work is done with Skills in the Actions drawer; smart agents are not the automations on the Agents page.

Agent types

The three presets carry their own instruction and ignore prompt.

Pricing

Always read the price from the quote's estimated_cost:

• custom_ai is priced like a Custom skill in the app: from an estimate of the work your prompt asks for, so a short classification prompt costs less than a research prompt. The run total is rounded up once to a whole credit.
• cold_intro_email is 3 credits per lead.
• Presets are 1 credit per lead.

The quote always shows the price that applies to your workspace.

Run a smart agent

POST /smart-agents/run

Scope: smart_agents:write

Request body

Quote first

Estimate with tool: "run_smart_agent" and the same list_id, agent_type, column_name, prompt, template_id, lead_scope, max_rows and overwrite you'll send to the run. Change any of them and the quote no longer matches.

# 1. Quote
curl -X POST https://api.cleanlist.ai/api/v2/credits/estimate \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "run_smart_agent",
    "list_id": "LIST_ID",
    "agent_type": "custom_ai",
    "column_name": "Fit Research",
    "prompt": "In two sentences, explain why this lead is or is not a strong outbound fit.",
    "lead_scope": "subset",
    "max_rows": 100
  }'
 
# 2. Run with the returned quote_id
curl -X POST https://api.cleanlist.ai/api/v2/smart-agents/run \
  -H "Authorization: Bearer clapi_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "list_id": "LIST_ID",
    "agent_type": "custom_ai",
    "column_name": "Fit Research",
    "prompt": "In two sentences, explain why this lead is or is not a strong outbound fit.",
    "lead_scope": "subset",
    "max_rows": 100,
    "quote_id": "qte_v1_..."
  }'

Response

{
  "smart_agent_task_id": "run_7c2a91",
  "smart_agent_task_ids": { "custom_ai": "run_7c2a91" },
  "status": "pending",
  "list_id": "LIST_ID",
  "column_name": "Fit Research",
  "estimated_cost": 40,
  "timestamp_ms": 1751404800000
}

The run starts in the background. Use smart_agent_task_id to poll. (The envelope's task_id is kept for older clients; new code should read smart_agent_task_id.) The credits for the run are taken when it starts, and estimated_cost shows the expected charge.

Cold intro emails

cold_intro_email needs two things, or it returns 400 validation_error:

• Enriched leads. Every lead in the selection must be enriched first. Run bulk enrichment, then get a new quote.
• An active email template in your workspace, or a template_id.

List runs

GET /smart-agents

Scope: smart_agents:read · Cost: free

{
  "runs": [
    {
      "task_id": "run_7c2a91",
      "list_id": "LIST_ID",
      "column_name": "Fit Research",
      "agent_type": "custom_ai",
      "status": "completed",
      "total": 100,
      "processed": 100,
      "failed": 2,
      "created_at": "2026-07-01T20:40:00Z"
    }
  ],
  "total": 1
}

Get results

GET /smart-agents/{smart_agent_task_id}

Scope: smart_agents:read · Cost: free

Poll until status is completed or failed (other states: pending, processing). The results array fills in as leads finish, so a running job returns a partial set.

{
  "smart_agent_task_id": "run_7c2a91",
  "status": "completed",
  "progress": 100,
  "total": 100,
  "succeeded": 98,
  "failed": 2,
  "results": [
    { "lead_id": "b2d4f6a8-...", "value": "Acme raised a Series B in March and is hiring SDRs; strong fit.", "error": null }
  ]
}

The output also appears as a column in the list in the app, and exports include it by default (include_smart_agents).

Errors

See Errors & Rate Limits for every code.

Related

• Credits & the quote model
• Polling & async results
• Lead Lists
• Skills in the app
• Export