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

# Lookalike Search

> Find people similar to a seed cohort using LinkedIn profiles or a CSV, then page the results by similarity.

## Endpoint

```http theme={null}
POST https://api.sixtyfour.ai/search/lookalike
GET  https://api.sixtyfour.ai/search/lookalike/{task_id}
```

```mermaid theme={null}
flowchart LR
  Seeds["LinkedIn URLs or CSV"] --> Start["POST /search/lookalike"]
  Start --> Poll["GET /search/lookalike/{task_id}"]
  Poll --> Results["POST /search/query"]
  Results --> Cursor["Continue with next_cursor"]
```

## Prepare the seed cohort

Every request accepts exactly one seed source.

| Seed source | Request field | Requirements |
| - | - | - |
| LinkedIn profiles | `linkedin_urls` | 1 to 1,000 LinkedIn profile URLs. Each URL must be 500 characters or fewer. |
| Uploaded CSV | `csv_resource_handle_id` | Handle returned by `POST /storage/csv/upload`. The CSV can contain up to 1,000 data rows. |

For CSV seeds, a LinkedIn profile URL column produces the most reliable identity matches. Recognized headers include `linkedin`, `linkedin url`, `linkedin profile`, and `profile url`. Rows without a LinkedIn URL need a full name plus supporting identity data such as company, company domain, role, location, or education. Sixtyfour drops weak or ambiguous identity matches instead of guessing.

`guidance` adds requirements the seeds do not imply, such as `"Only people in the United States with 8+ years of experience"`. The seeds define the audience.

## Run a lookalike search

Submit the seed cohort, poll the dedicated status endpoint until the search completes, then pass its `search_id` to `/search/query`.

The start request resolves the seeds before it returns, which takes up to 90 seconds. Set your client timeout to at least 100 seconds.

```bash cURL theme={null}
API_KEY="YOUR_API_KEY"
BASE_URL="https://api.sixtyfour.ai"

START_RESPONSE=$(curl -fsS --max-time 120 -X POST "$BASE_URL/search/lookalike" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "linkedin_urls": [
      "https://www.linkedin.com/in/saarthshah"
    ],
    "guidance": "Only people in the United States"
  }')

TASK_ID=$(printf '%s' "$START_RESPONSE" | jq -r '.task_id')
DEADLINE=$(( $(date +%s) + 30 * 60 ))

while true; do
  if [ "$(date +%s)" -ge "$DEADLINE" ]; then
    printf '%s\n' "Search did not complete within 30 minutes"
    exit 1
  fi

  HTTP_CODE=$(curl -sS --connect-timeout 10 --max-time 30 \
    -o status.json -D headers.txt -w '%{http_code}' \
    "$BASE_URL/search/lookalike/$TASK_ID?include_filters=false" \
    -H "x-api-key: $API_KEY")

  if [ "$HTTP_CODE" = "429" ] || [ "$HTTP_CODE" = "503" ]; then
    RETRY_AFTER=$(awk 'tolower($1) == "retry-after:" {print $2}' headers.txt | tr -d '\r')
    sleep "${RETRY_AFTER:-10}"
    continue
  fi
  if [ "$HTTP_CODE" != "200" ]; then
    cat status.json
    exit 1
  fi

  STATUS=$(jq -r '.status' status.json)
  if [ "$STATUS" = "completed" ]; then
    SEARCH_ID=$(jq -r '.search_id' status.json)
    break
  fi
  if [ "$STATUS" != "running" ]; then
    cat status.json
    exit 1
  fi

  sleep 10
done

curl -fsS -X POST "$BASE_URL/search/query" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"search_id\":\"$SEARCH_ID\",\"page_size\":25}"
```

```python Python theme={null}
import time

import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://api.sixtyfour.ai"
HEADERS = {
    "x-api-key": API_KEY,
    "Content-Type": "application/json",
}

start_response = requests.post(
    f"{BASE_URL}/search/lookalike",
    headers=HEADERS,
    json={
        "linkedin_urls": [
            "https://www.linkedin.com/in/saarthshah",
        ],
        "guidance": "Only people in the United States",
    },
    timeout=(10, 120),
)
start_response.raise_for_status()
task_id = start_response.json()["task_id"]
deadline = time.monotonic() + 30 * 60

while True:
    if time.monotonic() >= deadline:
        raise TimeoutError("Search did not complete within 30 minutes")
    status_response = requests.get(
        f"{BASE_URL}/search/lookalike/{task_id}",
        headers=HEADERS,
        params={"include_filters": "false"},
        timeout=(10, 30),
    )
    if status_response.status_code in (429, 503):
        time.sleep(int(status_response.headers.get("Retry-After", "10")))
        continue
    status_response.raise_for_status()
    status_data = status_response.json()

    if status_data["status"] == "completed":
        search_id = status_data["search_id"]
        break
    if status_data["status"] != "running":
        raise RuntimeError(
            status_data.get("error") or f"Search {status_data['status']}"
        )

    time.sleep(10)

page_response = requests.post(
    f"{BASE_URL}/search/query",
    headers=HEADERS,
    json={"search_id": search_id, "page_size": 25},
)
page_response.raise_for_status()
page = page_response.json()

for person in page["results"]:
    print(
        person["raw_source"].get("fullName"),
        person["raw_source"].get("headline"),
        person["raw_score"],
    )
```

```javascript JavaScript theme={null}
const API_KEY = "YOUR_API_KEY";
const BASE_URL = "https://api.sixtyfour.ai";
const headers = {
  "x-api-key": API_KEY,
  "Content-Type": "application/json",
};
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

async function requestJson(url, options = {}, timeoutMs = 30_000) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const response = await fetch(url, {
      ...options,
      signal: AbortSignal.timeout(timeoutMs),
    });
    if (response.status === 429 || response.status === 503) {
      await sleep(Number(response.headers.get("Retry-After") ?? 10) * 1000);
      continue;
    }
    if (!response.ok) {
      throw new Error(`${response.status}: ${await response.text()}`);
    }
    return response.json();
  }
  throw new Error(`${url} kept returning 429 or 503`);
}

async function main() {
  const started = await requestJson(
    `${BASE_URL}/search/lookalike`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        linkedin_urls: [
          "https://www.linkedin.com/in/saarthshah",
        ],
        guidance: "Only people in the United States",
      }),
    },
    120_000,
  );

  let searchId;
  const deadline = Date.now() + 30 * 60_000;
  while (!searchId) {
    if (Date.now() >= deadline) {
      throw new Error("Search did not complete within 30 minutes");
    }
    const params = new URLSearchParams({
      include_filters: "false",
    });
    const status = await requestJson(
      `${BASE_URL}/search/lookalike/${started.task_id}?${params}`,
      { headers },
    );

    if (status.status === "completed") {
      searchId = status.search_id;
      break;
    }
    if (status.status !== "running") {
      throw new Error(status.error ?? `Search ${status.status}`);
    }

    await sleep(10_000);
  }

  const page = await requestJson(
    `${BASE_URL}/search/query`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({ search_id: searchId, page_size: 25 }),
    },
    120_000,
  );

  for (const person of page.results) {
    console.log(
      person.raw_source?.fullName,
      person.raw_source?.headline,
      person.raw_score,
    );
  }
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});
```

> [!WARNING]
>
> Poll lookalike tasks with `GET /search/lookalike/{task_id}`, not `GET /search/status/{task_id}`. If your client gives up on the start request before it returns, do not submit it again automatically, the search may already be running.

## Start response

The start endpoint returns HTTP 202 after resolving the seeds and launching the search.

```json theme={null}
{
  "task_id": "lookalike_search_11111111-1111-4111-8111-111111111111",
  "search_id": "11111111-1111-4111-8111-111111111111",
  "status": "running",
  "seed_diagnostics": {
    "seed_type": "linkedin_urls",
    "supplied": 2,
    "parsed": 2,
    "resolved": 2,
    "skipped": 0,
    "analyzed": 2,
    "errors": [],
    "warnings": [],
    "identity_resolution": {
      "exact_matches": 2,
      "similarity_matches": 0,
      "dropped_below_threshold": 0,
      "ambiguous_matches": 0,
      "duplicates_removed": 0,
      "average_confidence": 1.0
    }
  }
}
```

`seed_diagnostics` reports how many seeds Sixtyfour resolved. The search runs when at least one seed resolves.

## Completed status

Poll every 10 seconds or slower, and stop on any status other than `running`: `completed`, `failed`, `cancelled`, `terminated`, or `timed_out`.

```json theme={null}
{
  "task_id": "lookalike_search_11111111-1111-4111-8111-111111111111",
  "status": "completed",
  "start_time": "2026-08-12T18:00:00+00:00",
  "close_time": "2026-08-12T18:02:14+00:00",
  "search_id": "11111111-1111-4111-8111-111111111111",
  "total_results": 12480,
  "seed_diagnostics": {
    "seed_type": "linkedin_urls",
    "supplied": 2,
    "parsed": 2,
    "resolved": 2,
    "skipped": 0,
    "analyzed": 2,
    "errors": [],
    "warnings": [],
    "identity_resolution": {
      "exact_matches": 2,
      "similarity_matches": 0,
      "dropped_below_threshold": 0,
      "ambiguous_matches": 0,
      "duplicates_removed": 0,
      "average_confidence": 1.0
    }
  },
  "excluded_public_ids": ["ada-lovelace", "grace-hopper"]
}
```

The status response also carries `filters`, which has no fixed shape. Set `include_filters=false` to omit it.

`total_results` counts everyone who matches `guidance`, without the seeds; `POST /search/query` returns up to `max_results` of them. `excluded_public_ids` lists the seed people, who are left out of results, replays, and exports. While the search is `running`, the response carries `progress_message`. Fields without a value are omitted.

## Page ranked results

Use the completed `search_id` for the first page:

```json theme={null}
{
  "search_id": "11111111-1111-4111-8111-111111111111",
  "page_size": 25
}
```

Rows are standard people-search rows, ordered by similarity to the cohort, with the score in `raw_score`. The seed people are excluded, so `total_available` is omitted:

```json theme={null}
{
  "search_id": "11111111-1111-4111-8111-111111111111",
  "next_cursor": "eyJ2IjoxLCJraWQiOiJr...",
  "cursor_expires_in_seconds": 1800,
  "has_more": true,
  "page_size": 25,
  "page_count": 25,
  "total_results": 25,
  "results": [
    {
      "raw_document_id": "jane-doe",
      "raw_source": {
        "publicId": "jane-doe",
        "fullName": "Saarth Shah",
        "headline": "Staff Data Engineer"
      },
      "raw_score": 0.78
    }
  ]
}
```

Paging follows the shared [cursor rules](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#paginate-with-cursors), and the full response is described in [Query response](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#query-response).

For every later page, send only the cursor returned by the previous response:

```json theme={null}
{
  "cursor": "eyJ2IjoxLCJraWQiOiJr..."
}
```

## Use a CSV seed cohort

A CSV seed file:

```csv theme={null}
linkedin_url,name,current_company,current_role
https://www.linkedin.com/in/saarthshah,Saarth Shah,Sixtyfour,Co-Founder & CEO
```

Upload it, then pass the returned `handle_id` as `csv_resource_handle_id`.

```bash cURL theme={null}
UPLOAD=$(curl -fsS -X POST "https://api.sixtyfour.ai/storage/csv/upload" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "file=@lookalike-seeds.csv;type=text/csv")

HANDLE_ID=$(printf '%s' "$UPLOAD" | jq -r '.handle_id')

curl -fsS -X POST "https://api.sixtyfour.ai/search/lookalike" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"csv_resource_handle_id\":\"$HANDLE_ID\"}"
```

```python Python theme={null}
import requests

headers = {"x-api-key": "YOUR_API_KEY"}

with open("lookalike-seeds.csv", "rb") as csv_file:
    upload_response = requests.post(
        "https://api.sixtyfour.ai/storage/csv/upload",
        headers=headers,
        files={"file": ("lookalike-seeds.csv", csv_file, "text/csv")},
    )
upload_response.raise_for_status()
handle_id = upload_response.json()["handle_id"]

start_response = requests.post(
    "https://api.sixtyfour.ai/search/lookalike",
    headers={headers, "Content-Type": "application/json"},
    json={"csv_resource_handle_id": handle_id},
)
start_response.raise_for_status()
print(start_response.json())
```

```javascript JavaScript theme={null}
import { readFile } from "node:fs/promises";

const headers = { "x-api-key": "YOUR_API_KEY" };
const csv = await readFile("lookalike-seeds.csv");
const form = new FormData();
form.append(
  "file",
  new Blob([csv], { type: "text/csv" }),
  "lookalike-seeds.csv",
);

const uploadResponse = await fetch(
  "https://api.sixtyfour.ai/storage/csv/upload",
  { method: "POST", headers, body: form },
);
if (!uploadResponse.ok) throw new Error(await uploadResponse.text());
const { handle_id } = await uploadResponse.json();

const startResponse = await fetch(
  "https://api.sixtyfour.ai/search/lookalike",
  {
    method: "POST",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ csv_resource_handle_id: handle_id }),
  },
);
if (!startResponse.ok) throw new Error(await startResponse.text());
console.log(await startResponse.json());
```

After the start call, use the same status and result-pagination flow shown above.

## Export results

Pass the completed lookalike `search_id` to `POST /search/export`, poll the returned export task through `GET /search/status/{task_id}`, then download the generated CSV. See [Export Search Results](https://docs.sixtyfour.ai/api-reference/legacy/search-results.md#export-search-results).

## Rate limits

For per-endpoint limits, see [Rate Limits](https://docs.sixtyfour.ai/api-reference/rate-limits.md#search).

## Pricing

See [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md) for more information.

## Related

* [Batch Processing](https://docs.sixtyfour.ai/guides/batch-processing.md)
* [Async Jobs](https://docs.sixtyfour.ai/api-reference/async-jobs.md)
* [Handling Errors](https://docs.sixtyfour.ai/api-reference/errors.md)
* [Credit Costs](https://docs.sixtyfour.ai/guides/credits-and-pricing.md)

> [!NOTE]
>
> For new integrations, see [Lookalike Search](https://docs.sixtyfour.ai/api-reference/search/lookalike-search.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.