---
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}`

## Request

- Base URL: `https://api.openfunnel.dev`
- URL: `https://api.openfunnel.dev/api/v1/account/search-lookalikes-bulk/{job_id}`
- Auth: none required
- TypeScript: <https://skmtc.dev/openfunnel/apis/openfunnel-agent-primitives/docs/api/v1/account/search-lookalikes-bulk/:job_id/get.ts> (a function with typed inputs; its response is checked against the schema)

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.dev/openfunnel/apis/openfunnel-agent-primitives.md) - [All operations](https://skmtc.dev/openfunnel/apis/openfunnel-agent-primitives/llms.txt) - [OpenAPI document](https://skmtc.dev/openfunnel/apis/openfunnel-agent-primitives/revisions/68cc95acb1f2?raw)