# Deep research for entity by name (async)

`GET /v2/entity-resolution/async`

> Tag: Entity resolution

Submit an async deep research request (3-5 minutes). Returns **202** with a `request_id`;
poll `/v2/entity-resolution/status/{request_id}` for the result.

Billed on submission. Polls are free, and a `FAILED` job is refunded automatically.

For sub-second results, try
[Instant Search](/docs/reference/instant-entity-search/get-v2-search/) first.

See also: [Batch processing](/docs/guides/batch-processing) ·
[Rate limits](/docs/rate-limits) · [Handling responses](/docs/handling-responses)

## Request

### Query parameters

- `name` (string, required) — Name of the entity to resolve
- `location` (string) — Optional location of the entity

### Example request

```bash
curl --request GET \
  --url 'https://api.savvyiq.ai/v2/entity-resolution/async?name=value' \
  --header 'apikey: YOUR_API_KEY'
```

## Responses

### 202 — Accepted and queued. Poll `/v2/entity-resolution/status/{request_id}` for the result.

- `request_id` (string, required)
- `status` (string (enum), required)

```json
{
  "request_id": "reqa_2ZUKmavJxCx4GHMnpJsc9",
  "status": "PENDING"
}
```

### 400 — Bad Request

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Bad request",
    "type": "bad_request"
  }
}
```

### 401 — Unauthorized

- `message` (string) — The error object.
- `request_id` (string) — The request ID for the error.

```json
{
  "message": "No API key found in request",
  "request_id": "d6ed1709fa87777bb373fd60a810e717"
}
```

### 402 — Your account balance is too low to cover this request. Top up and retry — nothing was charged and no job was created. Usage is drawn from your prepaid balance per request, so this means the balance ran short, not that a request quota was used up.

- `error` (string (enum)) — The reason the request was denied.
- `message` (string) — A human-readable explanation.

```json
{
  "error": "insufficient_credits",
  "message": "Insufficient credit balance. Please add credits to continue."
}
```

### 403 — This API is not enabled for your account. Topping up your balance will not change this — contact support.

- `error` (string (enum)) — The reason the request was denied.
- `message` (string) — A human-readable explanation.

```json
{
  "error": "insufficient_credits",
  "message": "Insufficient credit balance. Please add credits to continue."
}
```

### 429 — Either the per-minute rate limit (600 requests/minute per account on this endpoint, body `{ "message": … }`) or a plan limit — free-plan allowance, monthly request cap, monthly spend limit — which uses the `{ "error": …, "message": … }` body shown below. See [rate limits](/docs/rate-limits).

- `error` (string (enum)) — The reason the request was denied.
- `message` (string) — A human-readable explanation.

```json
{
  "error": "insufficient_credits",
  "message": "Insufficient credit balance. Please add credits to continue."
}
```

### 500 — Internal Server Error

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "An unexpected error occurred.",
    "type": "api_error"
  }
}
```

### 503 — Billing is temporarily unavailable. Nothing was charged. Retry with backoff.

- `error` (string (enum)) — The reason the request was denied.
- `message` (string) — A human-readable explanation.

```json
{
  "error": "insufficient_credits",
  "message": "Insufficient credit balance. Please add credits to continue."
}
```

### 504 — Gateway Timeout — the request was not accepted in time. Retry with backoff. Submission is not idempotent: if the first attempt did land, a retry creates a second job.

- `error` (object) — An error object.
  - `message` (string) — The error message
  - `type` (string) — The error code

```json
{
  "error": {
    "message": "Request timeout",
    "type": "timeout"
  }
}
```