> Reverse Contact API documentation. This is the Markdown copy of https://docs.reversecontact.com/sdk/javascript/tasks
> Every page is listed at https://docs.reversecontact.com/llms.txt, every endpoint with its credit cost and status at https://docs.reversecontact.com/catalog.json

# client.tasks

> Use client.tasks in the Reverse Contact TypeScript SDK to read or resume asynchronous live-fetch and contact tasks, handle failures and set wait deadlines.

- Last verified: 2026-11-04

Read or wait for the async tasks started by live fetches and contact lookups.

| Method | Endpoint | Cost |
| ------ | -------- | ---- |
| `client.tasks.retrieve()` | [Polling](https://docs.reversecontact.com/guides/polling) | Free and does not count toward rate limits. |
| `client.tasks.wait()` | [Polling](https://docs.reversecontact.com/guides/polling) | Free and does not count toward rate limits. |

Create `client` by following [Install and configure](https://docs.reversecontact.com/sdk/javascript/install). The examples use a saved `taskId` from the relevant task family. The `@reverse-contact/sdk` package exports `Body`, `Data`, `Query` and the other types used in the signatures.

JSON responses contain `data` and optional `quotas` and `metadata`. They also include the original `response`, with its body already read. See [First call](https://docs.reversecontact.com/sdk/javascript/first-call) for response handling.

HTTP errors use the [APIError subclasses and retry rules](https://docs.reversecontact.com/sdk/javascript/errors-and-retries): `BadRequestError`, `AuthenticationError`, `InsufficientCreditsError`, `PermissionDeniedError`, `NotFoundError`, `ConflictError`, `GoneError`, `UnprocessableEntityError`, `RateLimitError`, `DailyLimitError`, `KeyCreditLimitError`, `UnavailableForLegalReasonsError` and `InternalServerError`, according to the API response. Other statuses use `APIError`.

`client.tasks` reads the tasks of live fetches and contact lookups at `/v2/webhooks/:webhookId`. Bulk enrichment tasks, under `/v2/tasks/:taskId`, use [client.bulk](https://docs.reversecontact.com/sdk/javascript/bulk). The `Task` returned by a live fetch or contact lookup also has `task.retrieve()` and `task.wait()` methods. See [Async tasks](https://docs.reversecontact.com/sdk/javascript/async-tasks).

From SDK 0.4.0, `client.tasks`, `Task`, `TaskFailedError` and `TaskTimeoutError` replace `client.jobs`, `Job`, `JobFailedError` and `JobTimeoutError`. The former names remain as deprecated aliases of the same objects, so existing code and `instanceof` checks keep working, and the errors also expose `jobId` with the value of `taskId`.

## retrieve()

Read the current state of an async task. Use the `webhookId` from a live fetch or contact lookup, not a background Bulk task id.

**Signature**

```typescript [TypeScript SDK]
client.tasks.retrieve<T = unknown>(
  id: string,
  params?: {
    wait?: number;
  },
  options?: RequestOptions
): Promise<Result<TaskSnapshot<T>>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` **required** | `string` | Saved `task.id` / `webhookId` from a live fetch or contact lookup. |
| `params` | `{     wait?: number;   }` | Query parameters. Omit to use the defaults. |
| `params.wait` | `number` | Hold a long poll for 0 to 20 seconds. Defaults to 0. |
| `options` | `RequestOptions` | Optional per-request `timeout`, `maxRetries`, `headers` and `signal`. See [Client options](https://docs.reversecontact.com/sdk/javascript/client-options). |

**Returns**

`Result<TaskSnapshot<T>>` with `data.status`, `data.result` and `data.creditsConsumed`. You can inspect the snapshot even when the task has failed. Use `wait()` to raise an error on task failure.

**Errors**

Calls can raise the HTTP `APIError` subclasses listed above. Network failures or cancellation raise `APIConnectionError`, and attempt timeouts raise `APITimeoutError`. `ReverseContactError` reports invalid SDK options or an invalid successful JSON response.

**Example**

**Example**

```typescript [TypeScript SDK]
const snapshot = await client.tasks.retrieve(taskId, { wait: 20 });
console.log(snapshot.data.status, snapshot.data.result);
```

## wait()

Resume waiting for a saved live-fetch or contact task without submitting another paid lookup. The generic `T` describes the result type. The SDK does not validate the profile shape.

**Signature**

```typescript [TypeScript SDK]
client.tasks.wait<T = unknown>(
  id: string,
  options?: WaitOptions<TaskSnapshot<T>>
): Promise<Result<TaskSnapshot<T>>>
```

**Parameters**

| Name | Type | Description |
| ---- | ---- | ----------- |
| `id` **required** | `string` | Saved `task.id` / `webhookId` from a live fetch or contact lookup. |
| `options` | `WaitOptions<TaskSnapshot<T>>` | Optional overall `timeout`, `pollWait`, `onPoll`, `headers` and `signal`. See [Wait options](https://docs.reversecontact.com/sdk/javascript/timeouts). |

**Returns**

`Result<TaskSnapshot<T>>` once `data.status` is `succeeded`. A failed task raises `TaskFailedError` instead.

**Errors**

Calls can raise the HTTP `APIError` subclasses listed above. Network failures or cancellation raise `APIConnectionError`, and attempt timeouts raise `APITimeoutError`. `ReverseContactError` reports invalid SDK options or an invalid successful JSON response. Waiting raises `TaskFailedError` for an errored task and `TaskTimeoutError` when the overall deadline expires.

**Example**

**Example**

```typescript [TypeScript SDK]
const done = await client.tasks.wait(taskId, { timeout: 30 * 60 * 1000 });
console.log(done.data.result, done.data.creditsConsumed);
```

## Related guides

[Async tasks](https://docs.reversecontact.com/sdk/javascript/async-tasks), [client.bulk](https://docs.reversecontact.com/sdk/javascript/bulk), [Timeouts and cancellation](https://docs.reversecontact.com/sdk/javascript/timeouts). Return to the [TypeScript SDK overview](https://docs.reversecontact.com/sdk/javascript).

## FAQ

### Which task ids does client.tasks accept?

`client.tasks` accepts the task ids (`webhookId`) of live fetches and contact lookups. Use `client.bulk` for background Bulk task ids.

### Does client.tasks.wait start another paid lookup?

`client.tasks.wait()` polls an existing task for free. Waiting does not submit a replacement lookup.

### How does client.tasks report a failed task?

`client.tasks.retrieve()` returns the errored snapshot for inspection. `client.tasks.wait()` raises `TaskFailedError` when the task status is `errored`.