---
title: "Search Lookalikes Bulk Results"
method: GET
path: "/api/v1/account/search-lookalikes-bulk/{job_id}"
tags: ["Search Lookalikes Bulk Results"]
---

# Search Lookalikes Bulk Results

`GET /api/v1/account/search-lookalikes-bulk/{job_id}`

Poll a bulk lookalike job and page through its results. Submit a job first via **`POST /api/v1/account/search-lookalikes-bulk`** ("Search Lookalikes Bulk", under Company Search), which returns a `job_id`.

<Info>**No API key yet?** [Sign up via Agent Auth](/agent-primitives/authentication) to get your `X-API-Key` - the only required header for this endpoint.</Info>

This single endpoint returns both the job `status` (`pending` → `running` → `completed` / `failed`), a `manifest` summary once complete, **and** one page of result `rows`. Walk pages by passing the returned `next_cursor` as `?cursor=`.

**Check `status` for completion - not `next_cursor`.** A still-running job can return a null `next_cursor` simply because later pages haven't been written yet; only `status: "completed"` means the full result set is available.

No credits are charged for polling - the job's credits are billed once, when it completes.

## Path parameters

- `job_id` string, required

## Query parameters

- `cursor` string, nullable
- `limit` integer

## Headers

- `X-API-Key` string, required

## Response `200`

Job status, manifest, and one page of results.

- BulkLookalikeJobResponse — Combined job status + one page of results. Check `status` for completion (not `next_cursor`), and walk pages with `next_cursor`.
  - `job_id` string, required
  - `status` string, required — `pending`, `running`, `cancelling`, `cancelled`, `completed`, or `failed`. `cancelling` is transient (a cancel was requested); the job then settles to terminal `cancelled` with a `partial` manifest of the pages already delivered.
  - `manifest` BulkLookalikeManifest — Summary of a completed (or partial) bulk lookalike job, returned on the poll endpoint once the job finishes.
    - `count` integer, nullable — Total result rows produced. Null on a partial/failed job.
    - `pages` integer — Number of result pages available to walk via the poll endpoint.
    - `page_size` integer — Rows per page.
    - `credits_consumed` integer, nullable — Credits charged for the job (1 per returned company).
    - `derived_query` string, nullable — LLM-synthesized trait when `seed_domains` was used. Null for pure-query requests.
    - `resolved_seed_domains` string[], nullable
    - `unresolved_seed_domains` string[], nullable
    - `rerank_degraded` boolean — True if relevance ranking partially fell back to retrieval order (results are still complete; ordering past the head is approximate).
    - `partial` boolean — True if the job did not finish in full - failed OR cancelled after writing some pages; the pages that landed are still readable.
  - `error_message` string, nullable — Failure reason when `status` is `failed`.
  - `rows` BulkLookalikeResultRow[] — Companies in the requested page (same shape as Search Lookalikes results).
    - `name` string, nullable — Company name
    - `domain` string, nullable — Primary company domain
    - `linkedin_url` string, nullable — Company LinkedIn URL
    - `headquarters` string, nullable — Best available headquarters location
    - `match_reason` string, nullable — One-sentence LLM justification for why this company matches the trait query, with the supporting phrases from the company's description / industries wrapped in double quotes. Useful for human review of why a result was returned. May be null if the validator did not attach a reason.
    - `employee_count` integer, nullable — Estimated employee count. ClickHouse firmographic enrichment; null when the company did not resolve in ClickHouse.
  - `page` string, nullable — Name of the page returned, e.g. `page_0003`.
  - `next_cursor` string, nullable — Pass as `?cursor=` to fetch the next page; null on the last available page.
  - `count` integer — Number of rows in this page.
  - `processed` integer, nullable — Live progress: qualified companies delivered so far toward the requested limit. Null until the job starts producing progress.
  - `progress_message` string, nullable — Coarse stage label, e.g. `retrieving_companies` / `qualifying_companies` / `reranking_companies` / `completed` / `cancelled`.

## Other responses

- `404` — Job not found for this API key.
- `422` — Validation Error

---

[API](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives.md) · [All operations](https://skmtc.net/openfunnel/apis/openfunnel-agent-primitives/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openfunnel/openfunnel-agent-primitives/revisions/68cc95acb1f2/schema)