> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Scouts and signals

> 10 tools: heliyos_scouts_list, heliyos_scouts_get, heliyos_scouts_create, heliyos_scouts_update, heliyos_scouts_delete, heliyos_companies_scouts_list, heliyos_companies_scouts_add, heliyos_companies_scouts_remove, heliyos_signals_list, heliyos_signals_mark_read.

| Tool | What it does | Kind |
| - | - | - |
| [`heliyos_scouts_list`](#heliyos-scouts-list) | List scouts | Read |
| [`heliyos_scouts_get`](#heliyos-scouts-get) | Get a scout | Read |
| [`heliyos_scouts_create`](#heliyos-scouts-create) | Create a scout | Write |
| [`heliyos_scouts_update`](#heliyos-scouts-update) | Update a scout | Write |
| [`heliyos_scouts_delete`](#heliyos-scouts-delete) | Delete a scout | Destructive |
| [`heliyos_companies_scouts_list`](#heliyos-companies-scouts-list) | List a company's scouts | Read |
| [`heliyos_companies_scouts_add`](#heliyos-companies-scouts-add) | Add scouts to a company | Write |
| [`heliyos_companies_scouts_remove`](#heliyos-companies-scouts-remove) | Remove a company's scouts | Destructive |
| [`heliyos_signals_list`](#heliyos-signals-list) | List signals | Read |
| [`heliyos_signals_mark_read`](#heliyos-signals-mark-read) | Mark signals read | Write |

Write and destructive tools change your workspace. Clients that support it ask before they run.

## List scouts

`heliyos_scouts_list` · **Read** · Idempotent

Lists the workspace's scouts: the built-in (default) and custom monitors that look for events such as funding, hiring or leadership changes on watched companies or across the web. Shows each scout's id, whether it is active, its cadence, and how many signals it found (new of total). Returns every scout (there are only a few, so there is no paging). Use heliyos\_scouts\_get for one scout's query and recent signals, heliyos\_signals\_list for what scouts found. Returns structuredContent \{scouts:\[\{id, name, type, is\_active, ...}]}.

### Inputs

**type** `string`

Only built-in (default) or only custom scouts. One of `default`, `custom`.

**is\_active** `boolean`

Only active (true) or only paused and unconfirmed (false) scouts.

**apply\_to** `string`

Only scouts with this scope. One of `watchlist`, `selected_watchlist`, `entire_web`.

**response\_format** `string` (default: concise)

"concise" (default) returns one row per scout; "detailed" returns category, scope, effort and preview state too. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `scouts`.

### API endpoints

* [List workspace Scouts](https://docs.heliyos.ai/api-reference/scouts/list-workspace-scouts.md) · `GET /v1/platform/global-scouts`

## Get a scout

`heliyos_scouts_get` · **Read** · Idempotent

Fetches one scout by id: what it looks for (its query), cadence, effort, scope, whether it is active, its preview state (custom scouts) and its signal counts. "detailed" adds the 5 most recent signals with their ids and the full query. Returns structuredContent \{scout, recent\_signals?}.

### Inputs

**scout\_id** `string` *required*

Global scout id from heliyos\_scouts\_list. A 24-character hex id.

**response\_format** `string` (default: concise)

"concise" (default) returns the scout with its query cut at 1500 characters; "detailed" returns the full query and the 5 most recent signals. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `scout`, `recent_signals`.

### API endpoints

* [Get a workspace Scout](https://docs.heliyos.ai/api-reference/scouts/get-a-workspace-scout.md) · `GET /v1/platform/global-scouts/{id}`
* [List workspace Scout signals](https://docs.heliyos.ai/api-reference/signals/list-workspace-scout-signals.md) · `GET /v1/platform/global-scouts/{id}/signals`

## Create a scout

`heliyos_scouts_create` · **Write**

Creates a custom scout and starts a preview run of its query. The scout stays inactive until you confirm it: when heliyos\_scouts\_get shows preview completed, call heliyos\_scouts\_update with state "confirmed" to activate it on its companies. apply\_to: watchlist (every watched company, the default), selected\_watchlist (only selected\_company\_ids, which must be watched companies) or entire\_web. The scope cannot be changed later. Scout runs use credits. Calling this twice creates two scouts. Returns structuredContent \{scout}.

### Inputs

**name** `string` *required*

Scout name. Up to 200 characters.

**category** `string` *required*

A short category label, for example "Funding" or "Hiring". Up to 200 characters.

**query** `string` *required*

What to look for, in plain language. For watchlist scopes write it about "the company"; each company's name and website are added when it runs. For entire\_web, describe the event anywhere on the web. Up to 5000 characters.

**cadence** `string`

How often it runs: daily, weekly (default) or monthly. One of `daily`, `weekly`, `monthly`.

**effort** `string`

Search depth: low, medium (default) or high. Higher effort costs more credits per run. One of `low`, `medium`, `high`.

**apply\_to** `string`

watchlist (default), selected\_watchlist or entire\_web. Fixed once created. One of `watchlist`, `selected_watchlist`, `entire_web`.

**selected\_company\_ids** `string[]`

Watched company record ids the scout runs on (only with apply\_to selected\_watchlist). Up to 1000 items.

**preview\_company** `object`

selected\_watchlist only: the company the preview runs on.

**properties**

**name** `string` *required*

Company name. Up to 500 characters.

**website** `string`

Company website. Up to 2000 characters.

**preview\_lookback** `string`

How far back the preview searches: 1\_month (default), 3\_months or 6\_months. One of `1_month`, `3_months`, `6_months`.

### Returns

A readable text summary, plus `structuredContent` with `scout`.

### API endpoints

* [Create a custom Scout](https://docs.heliyos.ai/api-reference/scouts/create-a-custom-scout.md) · `POST /v1/platform/global-scouts`

## Update a scout

`heliyos_scouts_update` · **Write** · Idempotent

Changes a scout's name, category, query, cadence, effort or selected companies, and/or its state; what you leave out is kept. Changes apply to every company the scout runs on. state: "paused" stops it on every company, "active" resumes it, "confirmed" activates a new custom scout after its preview completed. The scope (apply\_to) cannot be changed. To delete a custom scout use heliyos\_scouts\_delete. Returns structuredContent \{scout}.

### Inputs

**scout\_id** `string` *required*

Global scout id from heliyos\_scouts\_list. A 24-character hex id.

**name** `string`

Scout name. Up to 200 characters.

**category** `string`

A short category label, for example "Funding" or "Hiring". Up to 200 characters.

**query** `string`

What to look for, in plain language. For watchlist scopes write it about "the company"; each company's name and website are added when it runs. For entire\_web, describe the event anywhere on the web. Up to 5000 characters.

**cadence** `string`

How often it runs: daily, weekly (default) or monthly. One of `daily`, `weekly`, `monthly`.

**effort** `string`

Search depth: low, medium (default) or high. Higher effort costs more credits per run. One of `low`, `medium`, `high`.

**selected\_company\_ids** `string[]`

Replaces the selected companies (selected\_watchlist scouts only). Up to 1000 items.

**state** `string`

"active", "paused", or "confirmed" (activate a custom scout once its preview completed). Applied after the field changes. One of `active`, `paused`, `confirmed`.

### Returns

A readable text summary, plus `structuredContent` with `scout`.

### API endpoints

* [Update a custom Scout](https://docs.heliyos.ai/api-reference/scouts/update-a-custom-scout.md) · `PATCH /v1/platform/global-scouts/{id}`
* [Set a workspace Scout state](https://docs.heliyos.ai/api-reference/scouts/set-a-workspace-scout-state.md) · `POST /v1/platform/global-scouts/{id}/state`

## Delete a scout

`heliyos_scouts_delete` · **Destructive** · Idempotent

Permanently deletes one custom scout and stops it on every company it runs on. Built-in (default) scouts cannot be deleted; pause them with heliyos\_scouts\_update state "paused". Signals it already found are kept. This cannot be undone: confirm with the user first. Returns structuredContent \{scout\_id, deleted, deleted\_company\_scouts}.

### Inputs

**scout\_id** `string` *required*

Global scout id from heliyos\_scouts\_list. A 24-character hex id.

### Returns

A readable text summary, plus `structuredContent` with `scout_id`, `deleted`, `deleted_company_scouts`.

### API endpoints

* [Delete a custom Scout](https://docs.heliyos.ai/api-reference/scouts/delete-a-custom-scout.md) · `DELETE /v1/platform/global-scouts/{id}`

## List a company's scouts

`heliyos_companies_scouts_list` · **Read** · Idempotent

Lists the scouts running on one company: each company scout's own id, its global scout id (scout\_id, for heliyos\_scouts\_get), status (active, paused or failed), cadence and last run. A company has only a few, so there is no paging. Returns structuredContent \{company\_id, scouts:\[\{id, scout\_id, name, status, ...}]}.

### Inputs

**company\_id** `string` *required*

Company record id (heliyos\_records\_lookup with object\_type company). A 24-character hex id.

**status** `string`

Only scouts in this status: active, paused or failed. One of `active`, `paused`, `failed`.

### Returns

A readable text summary, plus `structuredContent` with `company_id`, `scouts`.

### API endpoints

* [List company Scouts](https://docs.heliyos.ai/api-reference/scouts/list-company-scouts.md) · `GET /v1/platform/companies/{id}/scouts`

## Add scouts to a company

`heliyos_companies_scouts_add` · **Write**

Starts the given scouts on one company. Each scout\_id must be an active global scout with apply\_to watchlist (see heliyos\_scouts\_list). Setup runs in the background; check it with heliyos\_companies\_scouts\_list. A scout already running on the company is not added twice. Scout runs use credits. Returns structuredContent \{company\_id, scout\_ids, status}.

### Inputs

**company\_id** `string` *required*

Company record id (heliyos\_records\_lookup with object\_type company). A 24-character hex id.

**scout\_ids** `string[]` *required*

Global scout ids, 1 to 50. Up to 50 items.

### Returns

A readable text summary, plus `structuredContent` with `company_id`, `scout_ids`, `status`.

### API endpoints

* [Add Scouts to a company](https://docs.heliyos.ai/api-reference/scouts/add-scouts-to-a-company.md) · `POST /v1/platform/companies/{id}/scouts`

## Remove a company's scouts

`heliyos_companies_scouts_remove` · **Destructive** · Idempotent

Stops and removes EVERY scout running on one company (there is no per-scout removal). Signals already found are kept, and the company stays watched. This cannot be undone: confirm with the user first. Returns structuredContent \{company\_id, removed (company scout ids), failed}.

### Inputs

**company\_id** `string` *required*

Company record id (heliyos\_records\_lookup with object\_type company). A 24-character hex id.

### Returns

A readable text summary, plus `structuredContent` with `company_id`, `removed`, `failed`.

### API endpoints

* [Remove company Scouts](https://docs.heliyos.ai/api-reference/scouts/remove-company-scouts.md) · `DELETE /v1/platform/companies/{id}/scouts`

## List signals

`heliyos_signals_list` · **Read** · Idempotent

Lists signals (events scouts found, such as a funding round or a leadership change), newest first. Filter by company\_id, by scout\_id (a global scout from heliyos\_scouts\_list) and by status (new = unread). Each signal shows its id, date, company and a summary; detailed adds source URLs. Mark them read with heliyos\_signals\_mark\_read. Returns structuredContent \{signals:\[\{id, status, detected\_at, company\_id, company\_name, summary}], next\_cursor}.

### Inputs

**company\_id** `string`

Only signals about this company record. A 24-character hex id.

**scout\_id** `string`

Only signals found by this global scout. A 24-character hex id.

**status** `string`

new (unread), read or archived. One of `new`, `read`, `archived`.

**limit** `integer` (default: 20)

Signals per page, 1 to 100. Default 20. From 1 to 100.

**cursor** `string`

next\_cursor from the previous page, with the same limit. Omit for the first page. Up to 200 characters.

**response\_format** `string` (default: concise)

"concise" (default) returns one line per signal; "detailed" returns full summaries, source URLs and relevance. One of `concise`, `detailed`.

### Returns

A readable text summary, plus `structuredContent` with `signals`, `next_cursor`.

### API endpoints

* [List workspace Scout signals](https://docs.heliyos.ai/api-reference/signals/list-workspace-scout-signals.md) · `GET /v1/platform/global-scouts/{id}/signals`
* [List signals](https://docs.heliyos.ai/api-reference/signals/list-signals.md) · `GET /v1/platform/signals`

## Mark signals read

`heliyos_signals_mark_read` · **Write** · Idempotent

Marks signals read: either the given signal\_ids (1 to 20) or every new signal about one company (company\_id). Pass exactly one of the two. Marking a read signal again changes nothing. Returns structuredContent \{marked, failed} for signal\_ids, or \{company\_id, marked\_count} for a company.

### Inputs

**signal\_ids** `string[]`

Signal ids from heliyos\_signals\_list, 1 to 20. Up to 20 items.

**company\_id** `string`

Mark every new signal about this company read. A 24-character hex id.

### Returns

A readable text summary, plus `structuredContent` with `marked`, `failed`, `company_id`, `marked_count`.

### API endpoints

* [Mark signals read in bulk](https://docs.heliyos.ai/api-reference/signals/mark-signals-read-in-bulk.md) · `POST /v1/platform/signals/bulk-read`
* [Mark a signal read](https://docs.heliyos.ai/api-reference/signals/mark-a-signal-read.md) · `POST /v1/platform/signals/{id}/read`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.