Create an agent

An agent watches for one buying signal and drops whoever matches into a list, on a schedule. Signals → Agents describes what each kind finds; this page is how you create and run one over the API. Every endpoint here needs a key with the agents scope. The shape of the work is always the same:

Pick a kind

Each kind has its own create endpoint and its own config fields.

Save it as a draft

start: false (the default) costs nothing and lets you read the config back before committing.

Start it

Activation is free. The agent then charges per result it delivers, or per record it watches on each check.

Read the results list

The agent creates its own list and fills it as it runs.

Pick a kind

GET /business/agents/signal-types returns every kind you can create, with the type slug you post to.

curl https://api.tryfuse.ai/api/v1/business/agents/signal-types \
  -u "$FUSE_API_KEY:"

{
  "signalTypes": [
    { "type": "web-monitor", "title": "Website monitor", "category": "signal" },
    { "type": "person-starting-new-job", "title": "Person starting a new job", "category": "signal" }
  ]
}

The slug is the last path segment of the create call: POST /business/agents/web-monitor, POST /business/agents/funding-announcements, and so on. There are 18 of them, each with a different config — the API reference lists the exact fields per kind.

Every kind and what it needs

listName is required on all of them and is omitted below. Watchers also require exactly one of listId or listIds, the source list to watch.

Find new people and companies

Create with	Also required	Finds
`POST /business/agents/web-monitor`	`entityType`, `prompt`	Anything a natural-language web search turns up
`POST /business/agents/person-starting-new-job`	`industries`	People who just changed jobs
`POST /business/agents/person-discovery-via-filters`	At least one filter, such as `currentTitle` or `industries`	People matching a filter set
`POST /business/agents/linkedin-posts`	`keywords`	People posting about a topic
`POST /business/agents/job-postings`	`regions`	Companies hiring for a role
`POST /business/agents/job-posting-in-location`	`regions`	Companies hiring in a place
`POST /business/agents/funding-announcements`	`fundingRoundTypes`	Companies that just raised

Company growth signals

Create with	Also required	Finds
`POST /business/agents/company-headcount-growth`	`companyHeadcountGrowth`, `industries`, `regions`, `companyHeadcount`	Companies growing headcount within a band
`POST /business/agents/company-headcount-growth-over-baseline`	`regions`, `timeframe`, `industries`, `baselineHeadcount`, `companyHeadcountGrowthFromBaseline`	Growth measured against a fixed baseline
`POST /business/agents/company-department-headcount`	`departmentHeadcount`, `industries`, `regions`	Companies whose department hits a size
`POST /business/agents/first-person-hired-in-company-department`	`companyDepartment`, `industries`, `regions`, `companyHeadcount`	The first hire into a department
`POST /business/agents/first-person-hired-internationally`	`industries`, `regions`, `companyHeadcount`	A company’s first hire in a new country
`POST /business/agents/company-employee-job-location-in-two-countries`	`industries`, `regions`, `companyHeadcount`	Companies staffing across two countries

Watch a list you already have

Create with	Also required	Watches
`POST /business/agents/people-watcher`	`eventType`	Profile updates, posts, post engagement, open to work or hiring from people on a list
`POST /business/agents/companies-watcher`	`eventType`, plus `keywords` for job-posting events and `signalFilters.titleKeywords` for new hires	Job postings, posts, news, funding, new hires, status changes, new technology, acquisitions or layoffs at companies on a list. New hires delivers people.
`POST /business/agents/job-changes-watcher`	—	People on a list changing jobs

Scrape a known URL

Create with	Also required	Collects
`POST /business/agents/linkedin-profile`	`fieldsToScrape`, and `profileUrl` or `profileUrls` (up to 50)	People who liked or commented on recent posts by the profiles you name
`POST /business/agents/linkedin-post`	`fieldsToScrape`, and `postUrl` or `postUrls` (up to 50)	People who liked or commented on the posts you name

A watcher builds its own results list and never writes back into the list it watches, so the source list is left untouched.

Fill in the config

Two fields appear on every kind:

Field	What it does
`listName`	Names both the agent and the results list it creates. Must be unique across your lists and agents.
`start`	`false` (default) saves a draft. `true` creates and starts in one call.
`expirationDate`	`YYYY-MM-DD`, in the future. Omit it and the agent expires one month after creation; send `null` to run until you stop or delete it. A `web-monitor` has no end date when it is omitted, and a `job-changes-watcher` never expires.

Everything else is specific to the kind. A website monitor takes a prompt and an entityType; a funding agent takes fundingRoundTypes; a headcount agent takes a growth band.

Most config filters are accepted as plain strings by the service behind them. Send a value outside the accepted vocabulary and the agent is created — 201 Created — and then quietly matches nothing. There is no error to debug, so check your values before you start an agent.

Every field in the API reference states which values it takes and where they come from. See Finding accepted values for the general rules; the short version for agents is below.

Look up the canonical value

GET /business/agents/autocomplete resolves free text to the exact strings a config accepts. Both field and q are required.

curl -G https://api.tryfuse.ai/api/v1/business/agents/autocomplete \
  --data-urlencode "field=industry" \
  --data-urlencode "q=software" \
  -u "$FUSE_API_KEY:"

{ "field": "industry", "suggestions": ["software development", "computer software"] }

`field`	Feeds these config fields
`industry`	`industries`
`region`	`regions`, `authorLocation`
`title`	`currentTitle`, `pastTitle`, `authorTitle`
`school`	education filters

There is no country vocabulary. region returns LinkedIn geographies that include sub-national areas such as "California, United States", so it is not a source for companyCountries or leadCompanyCountries — those take full English country names ("United States", "Germany") and no endpoint serves them.

Fields with a short fixed vocabulary carry it inline in the API reference instead — headcount bands (1-10, 11-50, 51-200, …), timeframe (YoY, MoM, QoQ, 6M, 2Y), funding round types, departments.

Save a draft first

With start: false nothing is billed and nothing runs. You get an agent with status initializing.

curl -X POST https://api.tryfuse.ai/api/v1/business/agents/web-monitor \
  -u "$FUSE_API_KEY:" \
  -H "Content-Type: application/json" \
  -d '{
    "listName": "Regulator fines 2026",
    "entityType": "company",
    "prompt": "companies fined by a financial regulator",
    "searchPeriod": "1d",
    "maxCreditSpend": 5000
  }'

{
  "agent": {
    "id": "6a8dce4e65fd738c00d8927a",
    "type": "web-monitor",
    "name": "Regulator fines 2026",
    "status": "initializing",
    "started": false
  }
}

On a web monitor maxCreditSpend covers everything it ever delivers, so 5000 pauses this one after 100 results at 50 credits each. Read it back with GET /business/agents/{agentId} and adjust anything with PATCH /business/agents/{agentId} — the patch takes the same config fields and merges them, so you can send one key at a time.

Start it

POST /business/agents/{agentId}/activate starts the agent. It answers 202 with the agent’s new status, processing or active depending on the kind. Starting is free; the agent charges as it delivers or checks.

curl -X POST https://api.tryfuse.ai/api/v1/business/agents/6a8dce4e65fd738c00d8927a/activate \
  -u "$FUSE_API_KEY:"

Activation is draft-only. An agent that has already run — active, paused, expired — cannot be activated again, and pausing is one way: there is no resume in this API. To restart a paused agent, POST /business/agents/{agentId}/duplicate and activate the copy, which delivers into a new results list.

Passing start: true on the create call does both steps at once, without the chance to review the config first. It also reports a config problem as a specific error, where activating a draft with the same problem can answer 500 UNEXPECTED_ERROR.

Bound the spend

These fields decide what an agent can cost, and are worth setting explicitly:

Field	Effect
`maxCreditSpend`	Credit ceiling, 1,000 to 200,000. Discovery kinds apply it to each run. `web-monitor` applies it to everything the agent ever delivers, and pauses when it reaches it. `job-changes-watcher` applies it to each check, so it watches at most `maxCreditSpend` / 50 contacts.
`maxContacts`	Cap on how many results the agent delivers in total; it pauses when it gets there. Omit for no cap, except on the six headcount and first-hire kinds, which default to 200.
`notificationCount`	The most results one run delivers. Any positive integer. Only the discovery kinds take it, not `web-monitor`, the watchers or the scrapes.

Discovery agents bill 100 credits per contact or company delivered, and a web monitor 50 per result. The watchers bill 50 for every contact or company they watch, on every check: daily by default for the people and companies watchers, monthly for the job-changes watcher, and frequency changes it. See Credits for every kind.

Watch it and read results

GET /business/agents/{agentId} returns the agent with its current status:

Status	Meaning
`initializing`	A draft. Nothing has run or been billed.
`processing`	A run is in progress.
`active`	Running on its schedule.
`paused`	Stopped by you, or by Fuse when your balance ran short or the agent reached its result cap. Cannot be resumed over this API.
`expired`	Past its `expirationDate`.
`failed`	The run could not complete.

The agent’s own list holds the results — the listId on the agent’s row in GET /business/agents. GET /business/agents/{agentId} returns the config but not the list id. Read the list with GET /business/lists/{listId}/rows like any other list, which means custom columns, filters and exports all work on agent output.

To contact everyone an agent finds as soon as they arrive, point a dynamic campaign at its results list. Automate job change outreach walks through it, and Funding round outreach covers agents that deliver companies.

Housekeeping

Call	Notes
`GET /business/agents`	Every agent you own, `limit` and `pageNum` for paging.
`POST /business/agents/{agentId}/duplicate`	Copies an agent as a fresh draft — the quickest way to run a variant.
`POST /business/agents/{agentId}/stop`	Pauses it. One way.
`DELETE /business/agents/{agentId}`	Removes it. Answers `409` while a run is processing.

Errors worth handling

Status	Code	Meaning
`402`	`INSUFFICIENT_CREDITS`	Not enough credits to start a watcher or a scrape.
`403`	`AGENT_LIMIT_REACHED`	Free-plan workspaces hold at most 10 agents, drafts and duplicates included.
`409`	`LIST_NAME_TAKEN`	`listName` matches an existing list or agent.
`409`	`AGENT_NOT_A_DRAFT`	Activate was called on an agent that already ran.
`409`	`AGENT_NOT_RUNNING`	Stop was called on a draft, or on an agent with no live subscription.
`422`	`AGENT_SOURCE_LIST_EMPTY`	A watcher’s source list has nothing to watch.
`422`	`AGENT_SIGNAL_REJECTED`	The web monitor’s `prompt` was refused as a searchable signal. Rewrite it.
`409`	`AGENT_PROCESSING`	A run is in progress; the change has to wait.
`422`	`VALIDATION_FAILED`	A config field was the wrong shape. `param` names it.

The full list is in the error catalogue.

Get started

Concepts

Guides

Workflows

CRM sync

Power dialer

Deep Research

Signals

MCP server

Pick a kind

Every kind and what it needs

Find new people and companies

Company growth signals

Watch a list you already have

Scrape a known URL

Fill in the config

Look up the canonical value

Save a draft first

Start it

Bound the spend

Watch it and read results

Housekeeping

Errors worth handling

​Pick a kind

​Every kind and what it needs

​Find new people and companies

​Company growth signals

​Watch a list you already have

​Scrape a known URL

​Fill in the config

​Look up the canonical value

​Save a draft first

​Start it

​Bound the spend

​Watch it and read results

​Housekeeping

​Errors worth handling

Pick a kind

Every kind and what it needs

Find new people and companies

Company growth signals

Watch a list you already have

Scrape a known URL

Fill in the config

Look up the canonical value

Save a draft first

Start it

Bound the spend

Watch it and read results

Housekeeping

Errors worth handling