> ## 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.

# Create an agent

> Build a signal monitoring agent over the API — pick a kind, fill in its config, review it as a draft, then start it

An agent watches for one buying signal and drops whoever matches into a list, on a schedule. [Signals → Agents](/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](/concepts/scopes).

The shape of the work is always the same:

<Steps>
  <Step title="Pick a kind">
    Each kind has its own create endpoint and its own config fields.
  </Step>

  <Step title="Save it as a draft">
    `start: false` (the default) costs nothing and lets you read the config back before committing.
  </Step>

  <Step title="Start it">
    Activation is what spends credits.
  </Step>

  <Step title="Read the results list">
    The agent creates its own list and fills it as it runs.
  </Step>
</Steps>

## Pick a kind

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

```bash theme={null}
curl https://api.tryfuse.ai/api/v1/business/agents/signal-types \
  -u "$FUSE_API_KEY:"
```

```json theme={null}
{
  "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 |

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

## 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.

<Warning>
  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.
</Warning>

Every field in the API reference states which values it takes and where they come from. See [Finding accepted values](/concepts/field-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.

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

```json theme={null}
{ "field": "industry", "suggestions": ["software development", "computer software"] }
```

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

<Note>
  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.
</Note>

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`.

```bash theme={null}
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
  }'
```

```json theme={null}
{
  "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`.

```bash theme={null}
curl -X POST https://api.tryfuse.ai/api/v1/business/agents/6a8dce4e65fd738c00d8927a/activate \
  -u "$FUSE_API_KEY:"
```

<Warning>
  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.
</Warning>

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](/concepts/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](/concepts/errors).