--- title: "Create a companies watcher agent" method: POST path: "/business/agents/companies-watcher" tags: ["Agents"] --- # Create a companies watcher agent `POST /business/agents/companies-watcher` ## Request - Base URL: `https://api.tryfuse.ai/api/v1` - URL: `https://api.tryfuse.ai/api/v1/business/agents/companies-watcher` - Auth: HTTP basic Creates a Companies watcher (from a list) agent (`companies-watcher`). Watches the COMPANIES of an existing list (exactly one of `listId`/`listIds`) for the chosen `eventType`; job-posting watchers require at least one `keywords` entry and accept `jobPostingLocationTypes` (remote/on_site/hybrid). `company-watch-new-hires` watches the companies but collects the PEOPLE they hire: its results list is a contact list, and it requires `signalFilters.titleKeywords`. With `start: false` (the default) a DRAFT is saved — status `initializing`, nothing billed: read it back with GET /business/agents/{agentId}, adjust it with PATCH /business/agents/{agentId}, then start it with POST /business/agents/{agentId}/activate. With `start: true` the agent is created AND started in one call: its dedicated results list is created, credits are checked and spent, and the provider subscriptions are set up. Either way the answer is 201 `{ agent: { id, type, name, status, started } }` — the same shape for every agent kind, draft or started. Poll GET /business/agents for `status` and `contactsFound`, and read the delivered rows with the Lists endpoints via the agent's `listId`. Free-plan accounts hold at most 10 agents, drafts included (403 AGENT_LIMIT_REACHED). Every field below is validated by the agents service: a rejected field answers 422 VALIDATION_FAILED, naming it in `param` and describing every failure in `message`. `listName` must not collide with an existing list or agent name (409 LIST_NAME_TAKEN), and starting without enough credits answers 402 INSUFFICIENT_CREDITS without creating anything. Errors: - `422` `VALIDATION_FAILED` — The request was rejected by validation. Either this endpoint's own request validation (a malformed body), or the agent config itself: a field missing, out of range or not one of the accepted values, or a business rule broken (an `expirationDate` that is not in the future, more industries than the kind accepts, a notification count out of range). `param` names the first offending field and `message` lists every failure. - `409` `LIST_NAME_TAKEN` — `listName` is already used by one of your lists or agents. Pick another name. - `402` `INSUFFICIENT_CREDITS` — The workspace does not have enough credits to start this agent. Nothing was created or spent. - `403` `AGENT_LIMIT_REACHED` — Free-plan accounts may hold at most 10 agents, drafts included. Delete an agent or upgrade the plan. - `404` `LIST_NOT_FOUND` — A source list named in `listId` / `listIds` does not exist or does not belong to the token owner. - `422` `AGENT_SOURCE_LIST_EMPTY` — The source list holds nothing this agent kind can watch — no LinkedIn URLs, no companies, or no trackable contacts. Fill the list first. - `400` `INVALID_REQUEST` — The agents service rejected the request for a reason this API does not model specifically. The request is not retryable unchanged. - `429` `RATE_LIMITED` — The agents bucket is exhausted: 30 requests per minute or 2,000 per day per token owner, shared by every /business/agents operation (a 429 raised by the agents service is relayed with this code too). Retry after the `Retry-After` header. - `500` `UNEXPECTED_ERROR` — The agents service failed (5xx, refused service credential, or a timeout after 60s) or the rate limiter was unavailable. Retry later; quote `request_id` to support. Requires one of the following token scopes: agents. ## Request body - object - `start` boolean: true creates AND activates the agent (spends credits); false (default) saves a draft to activate later. - `listId` string: The existing SOURCE list(s) to watch, by id — the people/companies whose changes are tracked. - `listIds` string[]: The existing SOURCE list(s) to watch, by id: the companies whose changes are tracked. Each id is a list id from GET /business/lists. Every list you name is watched, their members are unioned and duplicate ids are collapsed, and there is no cap on how many lists; `listIds` and `listId` are mutually exclusive (sending both is rejected). A source list holding no companies is rejected when the agent starts (422 AGENT_SOURCE_LIST_EMPTY). - `listName` string, required: Name for BOTH the agent and the NEW dedicated results list this watcher creates. Must be unique — never reuse a source list's name; name it after the agent the user is creating. - `eventType` 'company-watch-linkedin-job-postings' | 'company-watch-linkedin-posts' | 'company-watch-press-mentions' | 'company-watch-funding-milestones' | 'company-watch-new-hires' | 'company-watch-status-changes' | 'company-watch-new-technologies' | 'company-watch-acquisitions' | 'company-watch-layoffs', required: Which change to watch on the companies in the source list(s). - `expirationDate` string, nullable: Date the agent stops running, as YYYY-MM-DD (for example "2026-12-31"), and in the future. Pass null to run until you pause or delete it; omit it for the default of one month from creation. - `keywords` string[]: Free text, matched as a keyword against the job POSTING TITLE upstream, never against the description (for example ["account executive", "sdr"]). At least one is required when eventType is company-watch-linkedin-job-postings, and the value is ignored entirely by the other event types. Every value must be distinct and non-empty: a repeated keyword is refused with 422 ("keywords must not contain duplicates") and so is an empty string. Values are passed to the provider as written, so near-duplicates that differ only by surrounding spaces are accepted and both kept. No cap on how many you send. - `jobPostingLocationTypes` string[]: Work arrangement of the job posting. Use one of exactly: remote, on_site, hybrid. Multiple values are OR-joined (a posting with any listed arrangement matches); there are only three values, so listing all three is the same as omitting the field, which matches any arrangement. Read only when eventType is company-watch-linkedin-job-postings. - `signalFilters` object: Filters on the watched signals. REQUIRED for company-watch-new-hires, which needs titleKeywords; optional for the other eventTypes. Each key names the eventType that takes it and is refused with any other. - `titleKeywords` string[]: company-watch-new-hires (required): the titles to watch hiring for, e.g. VP Sales, CTO. Fires when a watched company hires someone whose title contains one. Each value must be non-empty, without surrounding spaces, and distinct; anything else is refused with 422. - `minNewHires` integer: company-watch-new-hires: only fire when one check finds at least this many matching hires (default 1). - `toStatuses` string[]: company-watch-status-changes: only fire when the new status is one of these; "closed" includes a LinkedIn page going inactive. Values must be distinct. - `technologies` string[]: company-watch-new-technologies: only fire when one of these technologies is adopted, e.g. Snowflake, Salesforce. Each value must be non-empty, without surrounding spaces, and distinct; anything else is refused with 422. - `minPriceUsd` number: company-watch-acquisitions: only fire for acquisitions above this price, in USD. - `minPeopleAffected` integer: company-watch-layoffs: only fire when at least this many people were laid off. - `minPercentAffected` number: company-watch-layoffs: only fire when at least this percentage of the workforce was laid off. - `enrichPhone` boolean: company-watch-new-hires only (ignored for any other eventType): also enrich every delivered hire with a phone number. Costs additional credits per contact enriched. - `enrichEmail` boolean: company-watch-new-hires only (ignored for any other eventType): also enrich every delivered hire with a work email address. Costs additional credits per contact enriched. - `frequency` integer: How often the watcher checks its source list(s), in days (1-90, default 1). This is also its billing cadence. - `maxContacts` integer: Cap on the total number of results this agent delivers into its list. Omit for no cap. - `maxCreditSpend` integer: Maximum credits this agent may spend in a single run or refresh (1000 to 200000); delivery-driven monitors stop once their total delivered results reach it. Omit for no limit. ## Response `201` Success - object - `agent` object, required - `id` string, required: The new agent's id — pass it as `{agentId}` to every other agent operation. - `type` 'companies-watcher', required: The agent kind that was created — always this endpoint's own slug. - `name` string, required: The agent's name, echoed from `listName`; also the name of the results list it delivers into. - `status` 'initializing' | 'processing' | 'active', required: `initializing` when `start` was false (a draft). When `start` was true, the agent's real status right after starting: `processing` while the provider setup and first run are under way, `active` once it is running. - `started` boolean, required: Echoes the `start` you sent: false = a draft that still has to be activated; true = already running and already billing. ## Other responses - `400`: Error - `401`: Error - `402`: Error - `403`: Error - `404`: Error - `409`: Error - `422`: Error - `429`: Error - `500`: Error --- [API](https://skmtc.dev/fuseai/apis/fuse-business-api.md) · [All operations](https://skmtc.dev/fuseai/apis/fuse-business-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fuseai/apis/fuse-business-api/revisions/50d95e0536f4?raw)