Guides
API reference
MCP server
Changelogcurl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/global-scouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Hiring for data roles",
"category": "Hiring",
"queryTemplate": "New job postings at the company for data engineering or analytics roles.",
"cadence": "weekly",
"effort": "medium"
}
'{
"meta": {
"message": "Custom global scout created successfully"
},
"data": {
"_id": "6731c0a2b4e5f60718293a4b",
"organizationId": "66a0f1e2d3c4b5a697887766",
"name": "Hiring for data roles",
"type": "custom",
"applyTo": "watchlist",
"selectedCompanyIds": [],
"category": "Hiring",
"queryTemplate": "New job postings at the company for data engineering or analytics roles.",
"cadence": "weekly",
"effort": "medium",
"isActive": false,
"previewStatus": "running",
"previewRunId": "trun_4b8e2f1a9c7d",
"previewData": null,
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "system"
},
"updated": {
"at": "2026-11-04T09:30:01.000Z",
"by": "system"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Create a custom Scout
Creates a custom workspace Scout and starts a preview run of its query. The Scout is created inactive
(isActive: false) and does not run on any company yet.
- Create the Scout.
previewStatusisrunning(orfailedif the preview could not start; the Scout is still created). - Poll Get a workspace Scout (
GET /v1/platform/global-scouts/{id}) untilpreviewStatusiscompleted, and reviewpreviewData. - Send
{"state": "confirmed"}to Set a workspace Scout’s state (POST /v1/platform/global-scouts/{id}/state) to activate it, or{"state": "cancelled"}to discard it.
Once confirmed, the Scout runs on its scope at its cadence, and each run on a company (or on the web)
costs credits by effort: low 2.5, medium 7.5, high 10. Calling this twice creates two Scouts.
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/global-scouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Hiring for data roles",
"category": "Hiring",
"queryTemplate": "New job postings at the company for data engineering or analytics roles.",
"cadence": "weekly",
"effort": "medium"
}
'{
"meta": {
"message": "Custom global scout created successfully"
},
"data": {
"_id": "6731c0a2b4e5f60718293a4b",
"organizationId": "66a0f1e2d3c4b5a697887766",
"name": "Hiring for data roles",
"type": "custom",
"applyTo": "watchlist",
"selectedCompanyIds": [],
"category": "Hiring",
"queryTemplate": "New job postings at the company for data engineering or analytics roles.",
"cadence": "weekly",
"effort": "medium",
"isActive": false,
"previewStatus": "running",
"previewRunId": "trun_4b8e2f1a9c7d",
"previewData": null,
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "system"
},
"updated": {
"at": "2026-11-04T09:30:01.000Z",
"by": "system"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}heliyos_scouts_create.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Body
The Scout's name, 1 to 200 characters after trimming.
1 - 200"Hiring for data roles"
A short label, 1 to 200 characters after trimming. Signals inherit it.
1 - 200"Hiring"
What to look for, in plain language, 1 to 5,000 characters after trimming. For the 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.
1 - 5000"New job postings at the company for data engineering or analytics roles."
How often it runs: daily, weekly (default) or monthly.
daily, weekly, monthly "weekly"
The scope, fixed once created: watchlist (default, every watched company), selected_watchlist
(only selectedCompanyIds) or entire_web (one run across the web).
watchlist, selected_watchlist, entire_web "watchlist"
Search depth: low, medium (default) or high. Higher effort costs more credits per run.
low, medium, high "medium"
Required, with at least one id, when applyTo is selected_watchlist; ignored otherwise. Up to 1,000
company record ids, each a watched company in this workspace. Duplicates are removed.
1000A 24-character hexadecimal id.
^[0-9a-fA-F]{24}$selected_watchlist only: the company the preview runs on, as company_name (up to 500 characters)
and optional website (up to 2,000 characters). Ignored for other scopes or when company_name is empty.
Show child attributes
Show child attributes
How far back the preview searches: 1_month (default), 3_months or 6_months.
1_month, 3_months, 6_months "1_month"
The structured output each run returns. Send { "type": "json", "json_schema": { ... } } or a bare JSON
Schema object ({ "type": "object", "properties": { ... } }); anything else becomes an empty object
schema. In signals[].items, citations, confidence_score and source are removed and a sources
array is added. Omit it for the default schema (see the ScoutOutputSchema component).
Was this page helpful?