---
title: "Get correlation job status"
method: GET
path: "/correlate/{correlation_id}"
tags: ["correlation"]
---

# Get correlation job status

`GET /correlate/{correlation_id}`

## Request

- Base URL: `https://api.whoisgeni.us` (the document declares no server; this is the origin it was published from)
- URL: `https://api.whoisgeni.us/correlate/{correlation_id}`
- Auth: none declared

Poll the status of a correlation job.

Returns the current job status. When status is "completed", the full
correlation result (clusters, pairwise scores, summaries) is included.

## Path parameters

- `correlation_id` string, required

## Headers

- `X-API-Key` string, nullable

## Response `200`

Correlation job status and result

- ApiResponseCorrelateStatusResponse
  - `data` CorrelateStatusResponse: Response for polling correlation job status. Attributes: correlation_id: The correlation job identifier. status: Current job status (pending | processing | completed | failed). Always converges on a terminal value: a job that outlives its budget is reported ``failed`` rather than ``processing`` forever (#363). domain_count: Number of domains in the correlation. result: Correlation result when status is "completed". error: Error message when status is "failed". phase: Coarse progress hint while non-terminal (``queued`` -> ``analyzing`` -> ``correlating`` -> ``summarizing``). Cosmetic only, and distinct from ``status`` -- it lets a poller show real progress instead of an opaque "processing", and distinguishes a job still waiting for a worker (``queued``) from one being worked on.
    - `correlation_id` string, required
    - `status` string, required
    - `domain_count` integer, required
    - `result` CorrelationResult: Top-level correlation engine output. Contains clusters, pairwise scores, and unclustered domains for a cross-domain correlation analysis. Matches the design partner spec shape (Example 3 in output_examples.md).
      - `correlation_id` string, required
      - `domain_count` integer, required
      - `analyzed_at` string, required
      - `clusters` CorrelationCluster[], required
        - `cluster_id` string, required
        - `confidence` number, required
        - `domain_count` integer, required
        - `domains` string[], required
        - `shared_signals` SharedSignal[], required
          - `signal_type` string, required
          - `value` string, required
          - `domains_sharing` integer, required
          - `all_domains` boolean, required
          - `relation` 'owner' | 'host' | 'mixed'
        - `edges` ClusterEdge[]
          - `from_domain` string, required
          - `to_domain` string, required
          - `reason` string, required
        - `summary` string, nullable
        - `evidence` ClusterEvidence: Evidence ledger for one cluster's confidence score. Splits the reported confidence into the two components that ``ClusterBuilder._compute_confidence`` has always computed and then discarded: the mean intra-cluster pairwise score and the capped corroboration bonus for distinct owner-relation signal types.
          - `mean_pairwise_score` number
          - `corroboration_bonus` number
      - `unclustered_domains` string[], required
      - `pairwise` PairwiseScore[], required
        - `domain_a` string, required
        - `domain_b` string, required
        - `correlation` number, required
        - `shared_signals` string[], required
        - `matched_signals` PairwiseSignalMatch[]
          - `signal_type` string, required
          - `value` string, required
        - `evidence` PairwiseEvidence: Evidence ledger for one pairwise score. The public explainability contract for a pair: WHICH signals matched (type + value + strength bucket), how many signal types were available to compare (the dilution denominator, as a COUNT), and which scoring adjustments fired. Raw weight numbers are never exposed.
          - `signals` EvidenceSignal[]
            - `signal_type` string, required
            - `value` string, required
            - `strength_bucket` 'strong' | 'moderate' | 'weak', required
          - `available_signal_count` integer
          - `adjustments` string[]
          - `both_cdn` boolean
          - `score_pre_round` number
      - `correlation_summary` string, nullable
      - `excluded_domains` string[]
      - `degraded` boolean
    - `error` string, nullable
    - `phase` string, nullable
  - `error` ErrorDetail: Structured error information for API error responses. Attributes: code: Machine-readable error code (e.g. "JOB_NOT_FOUND"). message: Human-readable error description. details: Optional additional context for debugging.
    - `code` string, required
    - `message` string, required
    - `details` object, nullable
  - `meta` object, nullable

## Other responses

- `401`: Unauthorized — missing or invalid API key/JWT.
- `404`: Correlation job not found
- `422`: Validation Error

---

[API](https://skmtc.dev/whoisgeni/apis/whoisgenius.md) · [All operations](https://skmtc.dev/whoisgeni/apis/whoisgenius/llms.txt) · [OpenAPI document](https://skmtc.dev/whoisgeni/apis/whoisgenius/revisions/707f1c34f6b3?raw)