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 what spends credits.

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 20 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 additionally take the source list to watch (listId or listIds).

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`	—	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 or post activity from people on a list
`POST /business/agents/companies-watcher`	`eventType`	Job posts, posts, press or funding from companies on a list
`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`	Data from LinkedIn profiles you name
`POST /business/agents/linkedin-post`	`fieldsToScrape`	Engagement on LinkedIn 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 agents.
`start`	`false` (default) saves a draft. `true` creates and starts in one call.

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
  }
}

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 is what spends credits. It answers 202 and moves the agent to processing.

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. Pause an agent you still want and you will have to create a new one.

Passing start: true on the create call does both steps at once. It is the same spend, without the chance to review the config first.

Bound the spend

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

Field	Effect
`maxCreditSpend`	Hard ceiling on credits for a single run or refresh.
`maxContacts`	Cap on how many results the agent ever delivers. Omit for no cap.
`notificationCount`	Results delivered per run. Must be a positive multiple of 50.

Delivery is what costs — a web monitor bills 50 credits per delivered result. See Credits.

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. Cannot be resumed.
`expired`	Past its `expirationDate`.
`failed`	The run could not complete.

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

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 the run.
`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 an already-stopped agent.
`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

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