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

# Lookalike

> Find companies like the ones you already have.

`POST /v1/lookalike` answers: which companies look like these? Send the domains of companies you want more of, such as your best customers. Agentic ID reads what they have in common, searches for companies that fit, and ranks them by how alike they are. Use it when you can name good examples more easily than filters.

```bash curl theme={null}
curl -X POST https://YOUR_AGENTIC_ID_HOST/v1/lookalike \
  -H "Authorization: Bearer $AGENTIC_ID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 1d5f9b37-8a2c-4e6d-b4f0-6c8e0a2d4f57" \
  -d '{
    "seeds": ["acme.example", "globex.example"],
    "max_accounts": 2,
    "max_credits": 2
  }'
```

```typescript TypeScript theme={null}
import { AgenticId } from '@ic/agentic-id-sdk';

const client = new AgenticId({
  apiKey: process.env.AGENTIC_ID_API_KEY,
  baseUrl: 'https://YOUR_AGENTIC_ID_HOST',
});

const reply = await client.lookalike({
  seeds: ['acme.example', 'globex.example'],
  max_accounts: 2,
  max_credits: 2,
});
for (const a of reply.accounts) console.log(a.similarity, a.domain, a.why.join(', '));
```

```bash CLI theme={null}
agentic-id lookalike acme.example globex.example --max-accounts 2 --max-credits 2
```

```json 200 theme={null}
{
  "request_id": "req_a1c3e5f7-9b0d-4c2e-8a4f-6d8b0c2e4a68",
  "summary": "2 lookalikes from 2 seeds. 2 credits charged.",
  "cost": { "quoted_credits": 2, "charged_credits": 2 },
  "profile": {
    "countries": ["GB"],
    "industries": ["Software"],
    "employees": { "min": 201, "max": 1000 },
    "technologies": [],
    "seeds_used": 2
  },
  "seeds_rejected": [],
  "bigger_than_seeds": 0,
  "accounts": [
    {
      "id": "ic-2Fd6gJk0PmS8uXa4Bv7NqT",
      "name": "Initech Labs",
      "country": "GB",
      "domain": "initech.example",
      "employees": { "min": 201, "max": 500 },
      "size_check": "confirmed",
      "charged": true,
      "similarity": 1,
      "why": ["same industry", "similar size", "same country"]
    },
    {
      "id": "ic-5Wr1hYe9ZcD3oMf7Lp0KxU",
      "name": "Umbrella Data",
      "country": "GB",
      "domain": "umbrella.example",
      "employees": { "min": 501, "max": 1000 },
      "size_check": "confirmed",
      "charged": true,
      "similarity": 0.53,
      "why": ["similar size", "same country"]
    }
  ],
  "excluded": { "size_mismatch": 4 },
  "plan": [
    { "provider": "source-a", "why": "source-a applies countries, industries; we check size" }
  ]
}
```

## Request

**seeds** `string[]` *required*

Domains of companies you want more of. 1 to 50. Each up to 253 characters.

**max\_accounts** `integer` (default: 25)

The most companies to deliver. 1 to 500.

**exclude\_seen** `boolean` (default: true)

Skip companies already delivered to your workspace.

**purpose** `string` (default: b2b\_outbound)

Why you are asking. One of `b2b_outbound`, `ad_audience`, `own_customer_enrichment`, `fraud_check`. The call is refused if your workspace has not allowed the purpose.

**max\_credits** `integer`

The most this call may charge. 0 to 100000. Never charged past it.

## Response

**request\_id** `string` *required*

The ID of this call. The same value as the `X-Request-Id` header.

**summary** `string` *required*

One plain sentence: how many lookalikes from how many seeds, the charge, and why fewer came back than asked if that happened.

**cost** `object` *required*

**properties**

**quoted\_credits** `number` *required*

The most the call could have charged.

**charged\_credits** `number` *required*

What it charged. Never more than quoted.

**profile** `object` *required*

What the seeds have in common. This is the search that was run.

**properties**

**countries** `string[]` *required*

Countries the seeds share.

**industries** `string[]` *required*

Industries the seeds share.

**employees** `object`

The size range of the seeds: `min` (number) and `max` (number or `null`).

**technologies** `string[]` *required*

Technologies the seeds share.

**seeds\_used** `number` *required*

How many seeds the profile was built from.

**seeds\_rejected** `object[]` *required*

Seeds that could not be used, each with `domain` and `reason`.

**bigger\_than\_seeds** `number` *required*

Share of results bigger than your largest seed, from 0 to 1. A high value means the list leans to large, well-known companies.

**accounts** `object[]` *required*

The companies delivered, most alike first.

**properties**

**id** `string` *required*

The company's Agentic ID.

**name** `string`

Company name.

**domain** `string` *required*

Website domain.

**country** `string`

Country.

**employees** `object`

Size range: `min` (number) and `max` (number or `null`).

**size\_check** `string`

`confirmed`: two independent sources agree the size is in range. `single`: one source only, so the company is not charged. `not_filtered`: the profile had no size.

**charged** `boolean` *required*

Whether this company was charged.

**similarity** `number` *required*

How close the company is to the seed profile, from 0 to 1.

**why** `string[]` *required*

What it shares with the seeds, for example `same industry`, `similar size`, `same country`.

**excluded** `object` *required*

Why candidates were left out, as reason and count.

**plan** `object[]` *required*

Which source was asked and what it could filter itself, each with `provider` and `why`.

## What it costs

| Result | Credits |
| - | - |
| Each company delivered | 1 |
| A company with `size_check: "single"` | 0 |

* `quoted_credits` is `max_accounts`, or `max_credits` if that is lower.
* When `max_credits` is reached the search stops, and the summary says so.
* If your balance covers only part of the request, the part it covers is delivered.
* This reply has no `stopped_early` field. When the search stops at one of Agentic ID's own limits on paid sources, the summary says which one and what to do. The reasons are the same as for [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md#what-it-costs).

See [Credits](https://docs-agentic-id.icustomer.ai/credits.md) for how holds and charges work.

## Errors

| Status | Code | Meaning | Retry |
| - | - | - | - |
| 400 | `request.invalid` | The body does not match the schema, or `seeds` is empty or has more than 50 entries. | No. Fix the body. |
| 400 | `idempotency.key_invalid` | The `Idempotency-Key` is not 8 to 200 printable characters. | No. Fix the key. |
| 401 | `auth.invalid_key` | No valid credential was sent. | No. |
| 401 | `auth.token_expired` | Your sign-in has expired. | After you refresh the token. |
| 402 | `credits.insufficient` | No credits are available. Nothing was charged. | After adding credits. |
| 403 | `purpose.not_allowed` | Your workspace has not allowed this `purpose`. | No. |
| 409 | `idempotency.in_progress` | The first request with this key is still running. | Yes, after `Retry-After`, same key. |
| 422 | `lookalike.no_profile` | The seeds share no industry, country or size that could be read. `seedsRejected` lists the seeds that were not used. | No. Send different or more seeds. |
| 422 | `idempotency.key_reused` | The key was already used with a different body. | No. Use a new key. |
| 429 | `rate_limited` | Too many requests. | Yes, after `Retry-After`. |
| 502 | `service.error` | A fault on our side. | Yes, with the same `Idempotency-Key`. |
| 503 | `service.unavailable` | Temporarily unavailable. | Yes, after `Retry-After`, same key. |
| 504 | `service.timeout` | The call took too long. It may still have completed. | Yes, with the same `Idempotency-Key`. |

See [Errors](https://docs-agentic-id.icustomer.ai/errors.md) for the full list.

## Behaviour

* **Seeds are domains.** A seed that is not a readable domain, or about which nothing is known, is listed in `seeds_rejected` and left out of the profile. The call still runs on the rest.
* **Seeds never come back.** A seed is not returned as a lookalike of itself.
* **Read `profile` first.** It is the search that was run. If it is too broad, send seeds that have more in common.
* **Watch `bigger_than_seeds`.** When a quarter or more of the results are bigger than your largest seed, the summary says so.
* **`exclude_seen` is on by default.** Asking again returns the next companies. Those already delivered to your workspace are skipped.
* **Same checks as Discover.** Companies are judged and charged as in [Discover](https://docs-agentic-id.icustomer.ai/products/discover.md), including `size_check`.
* **Companies only.** To get people at the companies returned, call [Find](https://docs-agentic-id.icustomer.ai/products/find.md) with each `id`.


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