Launch a Signal Run

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, watchlist agents return one element per direction (inbound and outbound).

The signal_request_id and the {id} poll path parameter are IDs that are specific to your environment.

POST/api/v2/workspace/signal-runs

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). Only keyword agents use them; other 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 agents only.

The examples below use a keyword run. Most agents need only agent_id; keyword 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}}'

const response = await fetch('https://api.getsillage.com/api/v2/workspace/signal-runs', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SILLAGE_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agent_id: 42,
    parameters: { lookback_days: 90 },
  }),
})

const result = await response.json()

import { request } from 'node:https'

const body = JSON.stringify({
  agent_id: 42,
  parameters: { lookback_days: 90 },
})

const req = request(
  new URL('https://api.getsillage.com/api/v2/workspace/signal-runs'),
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SILLAGE_API_KEY}`,
      'Content-Type': 'application/json',
      'Content-Length': Buffer.byteLength(body),
    },
  },
  (res) => {
    let data = ''
    res.on('data', (chunk) => {
      data += chunk
    })
    res.on('end', () => {
      console.log(JSON.parse(data))
    })
  },
)

req.write(body)
req.end()

import os
import requests

response = requests.post(
    "https://api.getsillage.com/api/v2/workspace/signal-runs",
    json={
        "agent_id": 42,
        "parameters": {"lookback_days": 90},
    },
    headers={"Authorization": f"Bearer {os.environ['SILLAGE_API_KEY']}"},
    timeout=30,
)
response.raise_for_status()
result = response.json()

Example response — keyword agent

202 Accepted

[
  {
    "signal_request_id": 12345,
    "stage": "running"
  }
]

Example response — watchlist agent

202 Accepted

[
  {
    "signal_request_id": 12345,
    "stage": "running"
  },
  {
    "signal_request_id": 12346,
    "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.

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.
403	The workspace does not have access to this resource.
404	Agent not found or not accessible.
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"
}