Get results

Read an enrichment request with the enrichRequestId you got when you submitted it. The response tells you the request's overall status and, for each item, its own status and result.

GET https://app.knock-ai.com/v1/enrichment-requests/{enrichRequestId}

Reading a request never starts new enrichment, so polling costs nothing beyond the items you submitted (see Credits and side effects). Each read counts toward your rate limit.

Read a requestCopy Anchor Link

curl https://app.knock-ai.com/v1/enrichment-requests/7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14 \
  -H "x-api-key: $KNOCK_API_KEY"

{
  "enrichRequestId": "7d0f4f1e-2c3b-4a8e-9a51-0e6f3b8c2d14",
  "type": "people",
  "status": "in_progress",
  "createdAt": "2026-10-20T09:15:02.418Z",
  "items": [
    {
      "input": "jane@acme.com",
      "status": "completed",
      "result": {
        "firstName": "Jane",
        "lastName": "Doe",
        "title": "VP Sales",
        "seniority": "VP",
        "profession": "Sales",
        "linkedinUrl": "https://linkedin.com/in/janedoe",
        "location": "Austin, Texas, United States",
        "photoUrl": null,
        "currentPositionStartDate": "2024-03",
        "company": null
      }
    },
    { "input": "bob@globex.com", "status": "pending", "result": null },
    { "input": "nobody@initech.com", "status": "not_found", "result": null }
  ]
}

Response fieldsCopy Anchor Link

Every key is always present, including the null ones. A completed item's result can still be null in the rare case that Knock finished the item but holds no data for it, so check result before using it.

Match items to your recordsCopy Anchor Link

Items come back in the order you submitted them, but repeated inputs are collapsed into one item, so positions can shift. Match on input instead:

• People: input is the email trimmed and lowercased. Normalize your own emails the same way before looking them up: email.trim().toLowerCase().
• Companies: input is the exact string you sent. For repeated companies it's the first occurrence; later duplicates (for example acme.com after https://www.acme.com) map to that same item.

const byEmail = new Map(request.items.map((item) => [item.input, item]));

for (const lead of leads) {
  const item = byEmail.get(lead.email.trim().toLowerCase());
  if (item?.status === 'completed' && item.result) {
    saveEnrichment(lead.id, item.result);
  }
}

Poll until the request is finalCopy Anchor Link

A request is final once its status is completed, partially_completed or failed. Until then, read it again with a growing delay:

1. Start short. Some items are final within seconds, so make the first read after about 5 seconds.
2. Back off. Double the delay after every read that isn't final, up to a cap of about 2 minutes.
3. Honor 429. If you're rate limited, wait the number of seconds in the Retry-After header before the next read.
4. Retry temporary errors. 5xx responses (including 502 external-api.enrichment.unavailable) and brief 401s are never final answers. Back off and read again.
5. Stop at the deadline. An item still pending 24 hours after createdAt is settled on the first read after that point (or a later one, if Knock can't check it then). If a request is somehow still not final an hour after the deadline, stop polling and handle the remaining pending items as failed, or alert someone.

const BASE_URL = 'https://app.knock-ai.com';
const FINAL_STATUSES = new Set(['completed', 'partially_completed', 'failed']);
const DEADLINE_MS = 24 * 60 * 60 * 1000; // items still pending after 24 h settle on the next read
const GRACE_MS = 60 * 60 * 1000; // keep reading for 1 h after the deadline
const FIRST_DELAY_MS = 5_000;
const MAX_DELAY_MS = 2 * 60_000;
const MAX_AUTH_RETRIES = 5;

const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

/** Reads the request until it's final. Returns the last response either way. */
export async function waitForEnrichment(enrichRequestId) {
  let delay = FIRST_DELAY_MS;
  let authFailures = 0;
  const backOff = () => {
    delay = Math.min(delay * 2, MAX_DELAY_MS);
  };

  for (;;) {
    await sleep(delay);

    let res;
    try {
      res = await fetch(`${BASE_URL}/v1/enrichment-requests/${enrichRequestId}`, {
        headers: { 'x-api-key': process.env.KNOCK_API_KEY },
        signal: AbortSignal.timeout(30_000),
      });
    } catch {
      backOff(); // network error or timeout
      continue;
    }

    if (res.status === 429) {
      delay = Number(res.headers.get('retry-after') ?? 60) * 1000;
      continue;
    }
    if (res.status === 401 && authFailures < MAX_AUTH_RETRIES) {
      authFailures += 1; // Knock fails closed: a brief 401 can be temporary
      backOff();
      continue;
    }
    if (res.status >= 500) {
      backOff(); // temporary, never a final answer
      continue;
    }
    if (!res.ok) {
      // 400, 403, 404 or a persistent 401: reading again won't help.
      const error = await res.json().catch(() => ({}));
      throw new Error(`Reading ${enrichRequestId} failed: ${res.status} ${error.code ?? ''}`);
    }

    authFailures = 0;
    const request = await res.json();
    if (FINAL_STATUSES.has(request.status)) return request;

    const age = Date.now() - Date.parse(request.createdAt);
    if (age > DEADLINE_MS + GRACE_MS) {
      // Still not final well past the deadline: give up and treat pending items as failed.
      return request;
    }
    backOff();
  }
}

Budget your reads. All endpoints share one rate-limit bucket per account (600 requests per minute by default). At a 2-minute cap, each request in flight costs about one read every 2 minutes, so hundreds of requests can be polled at once with plenty of room for new submissions. If you have more in flight, raise the cap or poll requests in rotation.

Person resultCopy Anchor Link

result for a completed item in a people request. Every key is always present.

Company resultCopy Anchor Link

result for a completed item in a companies request, and the company of a person result. Every key is always present: text fields Knock has no data for are null, and list fields are empty arrays. Where a text field usually holds one of a known set of values, the typical values are listed, but treat them as free-form strings.

New fields may be added to these objects over time, so ignore fields you don't recognize (see Versioning).

ErrorsCopy Anchor Link

Authentication, permission and rate-limit errors apply too. See Errors and the API reference.

Keep your resultsCopy Anchor Link

Save each item's result on your side as soon as the item is final. Knock may remove old enrichment requests after a retention period, and there's no way to list past requests.