---
title: "Submit cross-domain correlation"
method: POST
path: "/correlate"
tags: ["correlation"]
---

# Submit cross-domain correlation

`POST /correlate`

## 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`
- Auth: none declared

Submit 2-100 domains for cross-domain correlation analysis.

Creates a background job to analyze uncached domains, compute pairwise
correlation scores, detect clusters, and generate LLM summaries.

Correlation is a credit-billed product available to any account with
sufficient credits (no subscription tier required — Gap G, Option A).

Credit billing: 1 credit per uncached domain + 1 for the correlation
compute, debited as ONE job-keyed charge (single settlement; exactly-once
via the ``charge:{job_id}`` ledger idempotency key). The charge is refunded
via the keyed settle path if dispatch fails or the job ends ``failed``.

## Headers

- `X-API-Key` string, nullable

## Request body

- CorrelateRequest: Request body for submitting a cross-domain correlation analysis. Attributes: domains: List of domain names to correlate (2-100). callback_url: Optional webhook URL for completion notification.
  - `domains` string[], required
  - `callback_url` string, nullable: Optional URL to receive a webhook POST when correlation completes

## Response `202`

Correlation job accepted

- ApiResponseCorrelateResponse
  - `data` CorrelateResponse: Response after submitting a correlation analysis (202 Accepted). Attributes: job_id: Unique correlation job identifier for polling status. correlation_id: Alias of ``job_id`` -- the value to pass to ``GET /correlate/{correlation_id}``. poll_url: Relative URL to poll for status/results. Correlation jobs are NOT retrievable from ``GET /jobs/{id}`` (that serves single-domain analysis only); this points at the correct endpoint. domain_count: Number of domains submitted. domains_cached: Number of domains with fully cached signals. domains_to_analyze: Number of domains needing fresh analysis. credits_charged: Total credits deducted for this request. status: Initial job status (always "pending").
    - `job_id` string, required
    - `correlation_id` string, required
    - `poll_url` string, required
    - `domain_count` integer, required
    - `domains_cached` integer, required
    - `domains_to_analyze` integer, required
    - `credits_charged` integer, required
    - `status` string
  - `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.
- `402`: Insufficient credits
- `422`: Invalid request (domain count out of range)

---

[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)