Launch Signal Run

Triggers an on-demand run for one of the workspace's agents. This works for every agent type — keyword_detection, job_posting_keyword_detection, job_update, customer, competitor, champion, influencer and partner — not just keyword detection. The kind of run is derived from the agent itself. The run starts immediately and responds with 202 Accepted.

Safe to retry — launching the same run again will not create duplicate matches.

Launch a signal run

POST/api/v2/partner/workspaces/{partner_workspace_id}/signal-runs

Path parameters

Parameter	Type	Description
partner_workspace_id	string	Opaque workspace identifier from the partner system.

Request body

Field	Type	Required	Description
agent_id	integer	Yes	The numeric id of the agent to run — any agent type. This ID is specific to your environment.
signal_key	string	Yes	Legacy field, required for backwards compatibility but not used: the run type is derived from the agent. Pass `keyword`.
parameters	object	Yes	Run parameters.
parameters.match_mode	string	No	`keyword_detection` agents only — whether to match posts containing `any` or `all` of the keywords. Defaults to `any`.

Example request

curl -X POST "https://api.getsillage.com/api/v2/partner/workspaces/ws_123/signal-runs" \
  -H "Authorization: Bearer $SILLAGE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": 42,
    "signal_key": "keyword",
    "parameters": { "match_mode": "any" }
  }'

Example response

Status: 202 Accepted

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

The response is an array of the runs that were started. Most agents start a single run; the watchlist-bound types (customer, competitor, champion) start two, so expect more than one entry for those.

Response fields

Field	Type	Description
[].signal_request_id	integer	Numeric id of a created run. Use this with the poll endpoint to track progress. This ID is specific to your environment.
[].stage	string	Current processing stage of the run.

Errors

Status	Meaning
400	Invalid request body or `id` parameter.
401	The master key is missing or invalid.
403	The master key is not authorized to access this resource.
404	No signal run found for this `id`.
500	An unexpected server error occurred.

Error responses use RFC 9457 problem documents with Content-Type: application/problem+json.