Launch a Signal Run
Start a detection run for an agent across your target accounts.
A signal run scans your target accounts using the agent's configured detection type and reports matches as they are found. The launch endpoint returns 202 Accepted immediately — poll the status endpoint until the run reaches a terminal stage (completed, completed_partial, or failed).
The response is an array: keyword and job-change agents return one element, interaction agents return one element per direction (inbound and outbound).
Champion-tracking agents can also be launched through this endpoint. They always return a single-element array, and any parameters you send are ignored — there is no lookback_days to set for this agent type. Launching one re-checks the people on the agent's bound watchlist for recent job changes; accounts checked within the last 30 days are skipped automatically. If the agent's previous run is still in progress, launching it again returns 409 Conflict.
The signal_request_id and the {id} poll path parameter are IDs that are specific to
your environment.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
| agent_id | integer | yes | The ID of the agent to run, from your Sillage workspace. This ID is specific to your environment. |
| parameters | object | no | Optional run parameters (see below). Keyword and interaction agents use them; champion-tracking agents ignore this field. |
| parameters.lookback_days | integer (1–180) | no | How many days back to scan for matches, counted from now. Defaults to 90. Keyword and interaction agents only. |
The examples below use a keyword run. Most agents need only agent_id; keyword and
interaction agents optionally accept lookback_days (see the table above).
Example request
curl -X POST "https://api.getsillage.com/api/v2/workspace/signal-runs" \
-H "Authorization: Bearer $SILLAGE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"agent_id":42,"parameters":{"lookback_days":90}}'Example response — keyword agent
202 Accepted
[
{
"signal_request_id": 12345,
"stage": "running"
}
]Example response — interaction agent
202 Accepted
[
{
"signal_request_id": 12345,
"stage": "running"
},
{
"signal_request_id": 12346,
"stage": "running"
}
]Example response — champion-tracking agent
202 Accepted
[
{
"signal_request_id": 12347,
"stage": "running"
}
]Response fields
The response is an array. Each element represents one detection direction that was started.
| Field | Type | Description |
|---|---|---|
| signal_request_id | integer | ID of this run. Use as {id} when polling. Specific to your environment. |
| stage | string | Always running on a successful launch. |
Behavior notes: each call starts a new run. Retrying the same run is safe — it will not create duplicate matches.
Each match a keyword agent finds costs 10 credits. A launch is refused with 402 when
your balance cannot cover a single match. If the balance runs out while the run is in
progress, the run keeps every match it could pay for, drops the rest, and ends without
an error. Workspaces billed through a partner are never refused and never interrupted
this way.
Errors
| Status | Meaning |
|---|---|
| 400 | Invalid request body, no target accounts are configured for this workspace, or the agent has no detection type configured. |
| 401 | The API key is missing or invalid. |
| 402 | Not enough credits to run this keyword agent. |
| 403 | The workspace does not have access to this resource. |
| 404 | Agent not found or not accessible. |
| 409 | A champion-tracking agent's previous run is still in progress. |
| 429 | Rate limit exceeded. |
| 500 | An unexpected server error occurred. |
Error responses use RFC 9457 problem documents with Content-Type: application/problem+json:
{
"type": "https://docs.getsillage.com/errors/bad-request",
"title": "Bad Request",
"status": 400,
"detail": "No top accounts configured for this workspace.",
"instance": "/api/v2/workspace/signal-runs"
}