> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openfunnel.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Search Lookalikes Bulk Results

> 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-auth/agent-auth/agent-sign-up) 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.



## OpenAPI

````yaml agent-primitives/openapi.json GET /api/v1/account/search-lookalikes-bulk/{job_id}
openapi: 3.1.0
info:
  title: OpenFunnel Agent Primitives
  version: 1.0.0
servers:
  - url: https://api.openfunnel.dev
security: []
paths:
  /api/v1/account/search-lookalikes-bulk/{job_id}:
    get:
      tags:
        - Search Lookalikes Bulk Results
      summary: Search Lookalikes Bulk Results
      description: >-
        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-auth/agent-auth/agent-sign-up) 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.
      operationId: >-
        search_lookalikes_bulk_status_api_v1_account_search_lookalikes_bulk__job_id__get
      parameters:
        - name: job_id
          in: path
          required: true
          schema:
            type: string
            title: Job Id
          description: The `job_id` returned by the bulk submit endpoint.
        - name: cursor
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Cursor
          description: >-
            Page to read, e.g. `page_0003` (use the `next_cursor` from the
            previous response). Omit for the first page.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 100
            title: Limit
          description: >-
            Accepted for forward-compatibility; page size is fixed at write
            time, so this is currently ignored.
        - name: X-API-Key
          in: header
          required: true
          schema:
            type: string
            title: X-Api-Key
      responses:
        '200':
          description: Job status, manifest, and one page of results.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkLookalikeJobResponse'
              example:
                job_id: d8a1bddb-44f1-4c7f-87a7-f37496354ff6
                status: completed
                manifest:
                  count: 600
                  pages: 6
                  page_size: 100
                  credits_consumed: 600
                  derived_query: null
                  resolved_seed_domains: null
                  unresolved_seed_domains: null
                  rerank_degraded: false
                  partial: false
                error_message: null
                rows:
                  - name: Acme Observability
                    domain: acme.com
                    linkedin_url: https://www.linkedin.com/company/acme
                    headquarters: San Francisco, United States
                    match_reason: >-
                      Describes itself as an "observability platform" for
                      engineering teams.
                    employee_count: 120
                page: page_0000
                next_cursor: page_0001
                count: 100
                processed: 600
                progress_message: completed
        '404':
          description: Job not found for this API key.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: bash
          label: Poll results
          source: >-
            # first page (also shows status)

            curl -sS
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes-bulk/JOB_ID"
            \
              -H "X-API-Key: YOUR_API_KEY"

            # next page

            curl -sS
            "https://api.openfunnel.dev/api/v1/account/search-lookalikes-bulk/JOB_ID?cursor=page_0001"
            \
              -H "X-API-Key: YOUR_API_KEY"
components:
  schemas:
    BulkLookalikeJobResponse:
      type: object
      title: BulkLookalikeJobResponse
      description: >-
        Combined job status + one page of results. Check `status` for completion
        (not `next_cursor`), and walk pages with `next_cursor`.
      required:
        - job_id
        - status
      properties:
        job_id:
          type: string
          title: Job Id
        status:
          type: string
          title: Status
          description: >-
            `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:
          anyOf:
            - $ref: '#/components/schemas/BulkLookalikeManifest'
            - type: 'null'
          description: Job summary; populated once the job completes.
        error_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Error Message
          description: Failure reason when `status` is `failed`.
        rows:
          type: array
          items:
            $ref: '#/components/schemas/BulkLookalikeResultRow'
          title: Rows
          description: >-
            Companies in the requested page (same shape as Search Lookalikes
            results).
        page:
          anyOf:
            - type: string
            - type: 'null'
          title: Page
          description: Name of the page returned, e.g. `page_0003`.
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
          description: >-
            Pass as `?cursor=` to fetch the next page; null on the last
            available page.
        count:
          type: integer
          default: 0
          title: Count
          description: Number of rows in this page.
        processed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Processed
          description: >-
            Live progress: qualified companies delivered so far toward the
            requested limit. Null until the job starts producing progress.
        progress_message:
          anyOf:
            - type: string
            - type: 'null'
          title: Progress Message
          description: >-
            Coarse stage label, e.g. `retrieving_companies` /
            `qualifying_companies` / `reranking_companies` / `completed` /
            `cancelled`.
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    BulkLookalikeManifest:
      type: object
      title: BulkLookalikeManifest
      description: >-
        Summary of a completed (or partial) bulk lookalike job, returned on the
        poll endpoint once the job finishes.
      properties:
        count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Count
          description: Total result rows produced. Null on a partial/failed job.
        pages:
          type: integer
          title: Pages
          description: Number of result pages available to walk via the poll endpoint.
        page_size:
          type: integer
          title: Page Size
          description: Rows per page.
        credits_consumed:
          anyOf:
            - type: integer
            - type: 'null'
          title: Credits Consumed
          description: Credits charged for the job (1 per returned company).
        derived_query:
          anyOf:
            - type: string
            - type: 'null'
          title: Derived Query
          description: >-
            LLM-synthesized trait when `seed_domains` was used. Null for
            pure-query requests.
        resolved_seed_domains:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Resolved Seed Domains
        unresolved_seed_domains:
          anyOf:
            - type: array
              items:
                type: string
            - type: 'null'
          title: Unresolved Seed Domains
        rerank_degraded:
          type: boolean
          default: false
          title: Rerank Degraded
          description: >-
            True if relevance ranking partially fell back to retrieval order
            (results are still complete; ordering past the head is approximate).
        partial:
          type: boolean
          default: false
          title: Partial
          description: >-
            True if the job did not finish in full - failed OR cancelled after
            writing some pages; the pages that landed are still readable.
    BulkLookalikeResultRow:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Company name
        domain:
          anyOf:
            - type: string
            - type: 'null'
          title: Domain
          description: Primary company domain
        linkedin_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Linkedin Url
          description: Company LinkedIn URL
        headquarters:
          anyOf:
            - type: string
            - type: 'null'
          title: Headquarters
          description: Best available headquarters location
        match_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Match Reason
          description: >-
            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:
          anyOf:
            - type: integer
            - type: 'null'
          title: Employee Count
          description: >-
            Estimated employee count. ClickHouse firmographic enrichment; null
            when the company did not resolve in ClickHouse.
      type: object
      title: InstantTraitSearchResult
      description: Single company returned by the public lookalike search endpoint.
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string

````