Poll a deep-dive job and read its result
ctscout_get_jobCheck the status of a submitted deep-dive job and retrieve its attribution results once complete. Poll until done to get the attribution table with confidence bands, signals, and evidence.
Instructions
Read the state of an asynchronous Pro deep dive submitted with ctscout_submit_deep_dive, via GET /jobs/{id}. Read-only and free to repeat: polling debits no quota.
Polling:
status is "queued" | "running" | "done" | "failed". Only "done" carries "result"; "failed" carries a short "error".
Back off: about 30 s before the first poll, then longer waits up to 5 min. A deep dive runs on a batch worker that picks up queued jobs every few minutes.
Pro only, and job ids are scoped to the submitting key: HTTP 404 means not your job or an unknown id.
Args:
job_id (string, required): the id returned by ctscout_submit_deep_dive.
response_format ('markdown' | 'json', default 'markdown'): output format.
Returns (on success, structuredContent follows the declared outputSchema; a failed call — 401, 403, 404, timeout — is isError with no structuredContent, so never dereference snapshot on a failed call):
In markdown: the job status lines; once done, the deep-dive attribution table (domain, attributed to, confidence band, signals, evidence) under a snapshot line. No /scan output carries this table.
In JSON, structured as: { "job_id": string, "kind": "deep_dive", "status": "queued" | "running" | "done" | "failed", "submitted_at": string, "started_at": string | null, "finished_at": string | null, "result": { // only when status is "done"; the deep-dive shape (see below), never returned by /scan "entity": {...}, "domains": [ { "domain": string, "attributed_to": string, "enrichment": {...}, "base": {...} } ], "run_metadata": {...}, "source": "live-enriched" | "cache-only", "signals_degraded": boolean, "snapshot": string, // warehouse date (YYYY-MM-DD) the deep dive read from — present, the batch worker sets it "worker_version": string, "signals_attempted": ... }, "error": string, // only when status is "failed" "snapshot": string | null, // copy of result.snapshot once done; null (unknown) before that "snapshot_source": "scan" | "unavailable" // 'scan' = the API response carried the date }
"Attributed" means the organization is what the evidence names for that domain, not an ownership claim. "Candidate" means a semantic name-similarity guess that is NOT an attribution. Deep dives return attributions with a confidence band (verified / likely / possible / insufficient), never bare candidates. When "signals_degraded" is true some signals errored: absence of their evidence is not evidence of absence.
Visual brand verification (VLM) is NOT included in v1: vlm_status stays "pending" or "skipped" and never vetoes a band.
Examples:
Use when: "Is my deep dive abc123 finished?" -> { job_id: "abc123" }
Don't use when: you have no job_id — submit first with ctscout_submit_deep_dive, or use the synchronous tools.
Corrections:
Wrong attribution? Open an issue at https://github.com/minghsuy/ctscout-mcp/issues. Missing entity? Email pro@ctscout.dev. Include the spec the job ran on, the result returned and why it is wrong.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | The job_id returned by ctscout_submit_deep_dive. | |
| response_format | No | Output format: 'markdown' for the job status and, once done, the deep-dive attribution table (band, signals, evidence); 'json' for the raw job record. | markdown |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| kind | No | 'deep_dive'. | |
| error | No | Short 'type: message' reason, present only when status is 'failed'. | |
| job_id | Yes | ||
| result | No | Present only when status is 'done'. | |
| status | Yes | 'queued' | 'running' | 'done' | 'failed'. | |
| snapshot | Yes | Warehouse/D1 sync date (YYYY-MM-DD) the answer was read from; the warehouse syncs daily. null when the API could not determine it. | |
| started_at | No | ||
| finished_at | No | ||
| submitted_at | Yes | ||
| snapshot_source | Yes | 'scan' = the API response carried the date; 'unavailable' = it did not, snapshot is null and must be treated as unknown, never as current. |