APIv3
Signal runs
Launch a detection run for a signal setup, follow it to completion and list the runs in progress.
A signal run looks for the detections of one signal setup, on your monitored accounts (account monitoring), beyond them (Discovery), or both, and reports detections as it finds them. Launch a run, then poll it until its status is completed or failed.
Endpoints
| Method | Path | Description |
|---|---|---|
| POST | /api/v3/signal-runs | Launch a signal run: start a run for a signal setup. |
| GET | /api/v3/signal-runs/{signal_run_id} | Get a signal run: follow a run until it finishes. |
| GET | /api/v3/signal-runs | List in-flight signal runs: see every run currently in progress. |
How a signal run reads
Launching a run, getting it, listing runs and the request status all answer the same run:
| Field | Type | Description |
|---|---|---|
| id | integer | ID of the signal run. |
| status | string | Where the run stands: pending, in_progress, completed or failed. See Run statuses. |
| label | string | A short readable description of the current step. |
| created_at | string (date-time) | When the run was started. |
| updated_at | string (date-time) | When the run was last updated. |
| companies | array | The accounts being scanned. An empty array means the run covers the whole workspace. |
| companies[].id | integer | ID of the company, as returned by POST /v3/companies/query. |
| companies[].name | string | null | Company name. |
| companies[].domain | string | null | Company domain. |
| companies[].linkedin_url | string | null | LinkedIn page of the company. |
| companies[].linkedin_handle | string | null | LinkedIn handle of the company. |
| companies[].logo_url | string | null | Logo of the company. |
| signal_setup_id | integer | null | ID of the signal setup the run belongs to, the same ID as in the client's signal setups. null when the run is not tied to one of the signal setups, for example a very old run, or a setup deleted while it was running. |
Getting a run adds metadata.
Run statuses
| Status | Meaning |
|---|---|
pending | The run is waiting to start. |
in_progress | The run is being processed. |
completed | The run finished. A run whose check failed for some accounts is still completed, and its label says some accounts could not be checked: its metadata lists those accounts when you get it. A run that could not start for some accounts is failed. |
failed | The run stopped without finishing. |
The list of in-flight runs only ever shows pending and in_progress runs.